<!DOCTYPE html>
<html xmlns='http://www.w3.org/1999/xhtml' xml:lang='en' lang='en'>
<head>
<title>cl-gserver documentation</title>
<link type='text/css' href='style.css' rel='stylesheet'/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<script src="jquery.min.js"></script>
<script src="toc.min.js"></script>
<script type="text/x-mathjax-config">
     MathJax.Hub.Config({
       tex2jax: {
         inlineMath: [['$','$']],
         processEscapes: true
       }
     });
   </script>
   <script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML">
   </script>
   </head>
<body>
<div id="content-container">
<div id="toc">
<div id="page-toc">
</div>
<div id="toc-footer"><ul><li><a href="https://github.com/melisgl/mgl-pax">[generated by MGL-PAX]</a></li></ul></div>
</div>
<div id="content">
<p><a id='x-28CL-GSERVER-2EDOCS-3A-40CL-GSERVER-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EDOCS-3A-40README-20MGL-PAX-3ASECTION-29" title="Introduction">&#8594;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40CL-GSERVER-20MGL-PAX-3ASECTION-29" title="cl-gserver documentation">&#8634;</a></span></span></p>

<h1><a href="#x-28CL-GSERVER-2EDOCS-3A-40CL-GSERVER-20MGL-PAX-3ASECTION-29">cl-gserver documentation</a></h1>

<h2>Table of Contents</h2>

<ul>
<li><a href="#x-28CL-GSERVER-2EDOCS-3A-40README-20MGL-PAX-3ASECTION-29" title="Introduction">1 Introduction</a></li>
<li><a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">2 API documentation</a>

<ul>
<li><a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-40ACTOR-SYSTEM-20MGL-PAX-3ASECTION-29" title="Actor-System">2.1 Actor-System</a></li>
<li><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40ACTOR-CONTEXT-20MGL-PAX-3ASECTION-29" title="Actor-Context">2.2 Actor-Context</a>

<ul>
<li><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40AC-PROTOCOL-20MGL-PAX-3ASECTION-29" title="Actor-Context protocol">2.2.1 Actor-Context protocol</a></li>
</ul></li>
<li><a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">2.3 Actor</a>

<ul>
<li><a href="#x-28CL-GSERVER-2EACTOR-CELL-3A-40ACTOR-CELL-20MGL-PAX-3ASECTION-29" title="Actor-Cell">2.3.1 Actor-Cell</a></li>
<li><a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-BASE-20MGL-PAX-3ASECTION-29" title="Message-box base class">2.3.2 Message-box base class</a></li>
<li><a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FBT-20MGL-PAX-3ASECTION-29" title="Message-box threaded">2.3.3 Message-box threaded</a></li>
<li><a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FDP-20MGL-PAX-3ASECTION-29" title="Message-box dispatched">2.3.4 Message-box dispatched</a></li>
<li><a href="#x-28CL-GSERVER-2EFUTURE-3A-40FUTURE-20MGL-PAX-3ASECTION-29" title="Future (delayed-computation)">2.3.5 Future (delayed-computation)</a></li>
</ul></li>
<li><a href="#x-28CL-GSERVER-2EAGENT-3A-40AGENT-20MGL-PAX-3ASECTION-29" title="Agent">2.4 Agent</a>

<ul>
<li><a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3A-40HASH-AGENT-20MGL-PAX-3ASECTION-29" title="Hash-table agent">2.4.1 Hash-table agent</a></li>
</ul></li>
<li><a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40DISPATCHER-20MGL-PAX-3ASECTION-29" title="Dispatcher">2.5 Dispatcher</a>

<ul>
<li><a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40SHARED-DISPATCHER-20MGL-PAX-3ASECTION-29" title="Shared dispatcher">2.5.1 Shared dispatcher</a></li>
</ul></li>
<li><a href="#x-28CL-GSERVER-2EROUTER-3A-40ROUTER-20MGL-PAX-3ASECTION-29" title="Router">2.6 Router</a></li>
<li><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3A-40EVENTSTREAM-20MGL-PAX-3ASECTION-29" title="Eventstream">2.7 Eventstream</a></li>
<li><a href="#x-28CL-GSERVER-2ETASKS-3A-40TASKS-20MGL-PAX-3ASECTION-29" title="Tasks">2.8 Tasks</a></li>
<li><a href="#x-28CL-GSERVER-2ECONFIG-3A-40CONFIG-20MGL-PAX-3ASECTION-29" title="Config">2.9 Config</a></li>
</ul></li>
</ul>

<h6>[in package CL-GSERVER.DOCS]</h6>

<p><a id='x-28CL-GSERVER-2EDOCS-3A-40README-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EDOCS-3A-40CL-GSERVER-20MGL-PAX-3ASECTION-29" title="cl-gserver documentation">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40CL-GSERVER-20MGL-PAX-3ASECTION-29" title="cl-gserver documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8594;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40README-20MGL-PAX-3ASECTION-29" title="Introduction">&#8634;</a></span></span></p>

<h2><a href="#x-28CL-GSERVER-2EDOCS-3A-40README-20MGL-PAX-3ASECTION-29">1 Introduction</a></h2>

<p><a id='x-28CL-GSERVER-2EDOCS-3A-3AREADME-2EMD-20-28MGL-PAX-3AINCLUDE-20-23P-22-2FUsers-2Fmbergmann-2FDevelopment-2FMySources-2Fcl-gserver-2FREADME-2Emd-22-29-29'></a></p>

<h3>Introduction - Actor framework featuring actors and agents</h3>

<p>cl-gserver is a 'message passing' library/framework with actors similar to Erlang or Akka. It supports creating systems that should work reactive, require parallel computing and event based message handling.</p>

<h3>Version history</h3>

<p><strong>Version 1.7.6:</strong> Added cl:hash-table based agent with similar API interface.</p>

<p><strong>Version 1.7.5:</strong> Allow agent to specify the dispatcher to be used.</p>

<p><strong>Version 1.7.4:</strong> more convenience additions for task-async (completion-handler)</p>

<p><strong>Version 1.7.3:</strong> cleaned up dependencies. Now cl-gserver works on SBCL, CCL, LispWorks, Allegro and ABCL</p>

<p><strong>Version 1.7.2:</strong> allowing to choose the dispatcher strategy via configuration</p>

<p><strong>Version 1.7.1:</strong> added possibility to create additional and custom dispatchers. I.e. to be used with <code>tasks</code>.</p>

<p><strong>Version 1.7.0:</strong> added tasks abstraction facility to more easily deal with asynchronous and concurrent operations.</p>

<p><strong>Version 1.6.0:</strong> added eventstream facility for building event based systems. Plus documentation improvements.</p>

<p><strong>Version 1.5.0:</strong> added configuration structure. actor-system can now be created with a configuration. More configuration options to come.</p>

<p><strong>Version 1.4.1:</strong> changed documentation to the excellent <a href="https://github.com/melisgl/mgl-pax" >mgl-pax</a></p>

<p><strong>Version 1.4:</strong> convenience macro for creating actor. See below for more details</p>

<p><strong>Version 1.3.1:</strong> round-robin strategy for router</p>

<p><strong>Version 1.3:</strong> agents can be created in actor-system</p>

<p><strong>Version 1.2:</strong> introduces a breaking change</p>

<p><code>ask</code> has been renamed to <code>ask-s</code>.</p>

<p><code>async-ask</code> has been renamed to <code>ask</code>.</p>

<p>The proposed default way to query for a result from another actor should
be an asynchronous <code>ask</code>. <code>ask-s</code> (synchronous) is
of course still possible.</p>

<p><strong>Version 1.0</strong> of <code>cl-gserver</code> library comes with quite a
few new features (compared to the previous 0.x versions). 
One of the major new features is that an actor is not
bound to it's own message dispatcher thread. Instead, when an
<code>actor-system</code> is set-up, actors can use a shared pool of
message dispatchers which effectively allows to create millions of
actors.</p>

<p>It is now possible to create actor hierarchies. An actor can have child
actors. An actor now can also 'watch' another actor to get notified
about it's termination.</p>

<p>It is also possible to specify timeouts for the <code>ask-s</code> and
<code>ask</code> functionality.</p>

<p>This new version is closer to Akka (the actor model framework on the
JVM) than to GenServer on Erlang. This is because Common Lisp from a
runtime perspective is closer to JVM than to Erlang/OTP. Threads in
Common Lisp are heavy weight OS threads rather than user-space low
weight 'Erlang' threads (I'd like to avoid 'green threads', because
threads in Erlang are not really green threads). While on Erlang it is
easily possible to spawn millions of processes/threads and so each actor
(GenServer) has its own process, this model is not possible when the
threads are OS threads, because of OS resource limits. This is the main
reason for working with the message dispatcher pool instead.</p>

<p>But let's jump right into it. I'll explain more later.</p>

<h3>Getting hands-on</h3>

<h4>Creating an actor-system</h4>

<p>To use the shared dispatcher pool we have to create an
<code>actor-system</code> first.</p>

<pre><code><span class="code"><span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_143.html#IDX430" class="symbol"><i><span class="symbol">defvar</span></i></a> <span class="special">*system*</span> <span class="paren2">(<span class="code">asys:make-actor-system</span>)</span></span>)</span></span></code></pre>

<p>When we eval <code>*system*</code> in the repl we see a bit of the structure:</p>

<pre><code>#&lt;ACTOR-SYSTEM shared-workers: 4, user actors: 0, internal actors: 0&gt;</code></pre>

<p>So the <code>actor-system</code> has by default four shared message
dispatcher workers. Depending on how busy the system tends to be this
default can of course be increased.</p>

<p>An optional configuration can be passed to the actor-system factory function. See API documentation.</p>

<ol>
<li><p>Shutting down the system</p>

<p>Shutting down an actor system may be necessary depending on how
it's used. It can be done by:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">ac:shutdown <span class="special">*system*</span></span>)</span></span></code></pre>

<p>This will stop all dispatcher workers and all other actors that have
been spawned in the system.</p></li>
</ol>

<h4>Creating actors</h4>

<p>Actors kind of live within an <code>actor-context</code>. An
<code>actor-context</code> contains a collection (of actors) and defines a Common
Lisp protocol that defines a set of generic functions for creating, removing and finding actors in an <code>actor-context</code>.</p>

<p>There are two 'things' that host an <code>actor-context</code>. This
is:</p>

<ol>
<li>the <code>actor-system</code>. Creating actors on the <code>actor-system</code> will create root actors.</li>
<li>the <code>actor</code>. Creating actors on the context of an actor will create a child actor.</li>
</ol>

<p>Let's create an actor.</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">act:actor-of <span class="paren2">(<span class="code"><span class="special">*system*</span> <span class="string">"answerer"</span></span>)</span>
  <span class="keyword">:receive</span>
  <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">self msg state</span>)</span>
    <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_141.html#IDX422" class="symbol"><i><span class="symbol">let</span></i></a> <span class="paren4">(<span class="code"><span class="paren5">(<span class="code">output <span class="paren6">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_75.html#IDX176" class="symbol">format</a> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_6.html#SEC6" class="symbol">nil</a> <span class="string">"Hello ~a"</span> msg</span>)</span></span>)</span></span>)</span>
      <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_75.html#IDX176" class="symbol">format</a> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_266.html#IDX704" class="symbol">t</a> <span class="string">"~a~%"</span> output</span>)</span>
      <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_83.html#IDX221" class="symbol">cons</a> output state</span>)</span></span>)</span></span>)</span></span>)</span></span></code></pre>

<p>This creates a root actor on the <code>*system*</code>. Notice that the actor is not assigned to a variable. It is now registered in the system. The <code>:receive</code> key argument to the <code>actor-of</code> macro is a function which does the main message processing of an actor. The parameters to the 'receive' function are the tuple:</p>

<ol>
<li><code>self</code> - the instance of the actor</li>
<li><code>msg</code> - the received message of when this 'receive' function is called</li>
<li><code>state</code> - the current state of the actor</li>
</ol>

<p><code>actor-of</code> also allows to specify the initial state by using the <code>:state</code> key, a name, and a custom actor type. By default a standard actor of type <code>'actor</code> is created. But you can subclass <code>'actor</code> and specify your own. It is also possible to add 'after initialization' code using the <code>:init</code> key which takes a lambda with the actor instance as parameter.</p>

<p>The return value of the 'receive' function should also be familiar. It is the <code>cons</code> with <code>car</code> being sent back to sender (in case of ask/ask-s) and <code>cdr</code> set as the new state of the actor.</p>

<p>The <code>actor-of</code> macro still returns the actor as can be seen on the repl when this is executed. So it is of course possible to store the actor in a dynamic or lexical context. However, when the lexical context ends, the actor will still live as part of the actor context/system.</p>

<p>Here we see a few details of the actor. Among which is the name and also the type of message-box it uses. By default it is a <code>message-box/dp</code> which is the type of a shared message dispatcher message-box.</p>

<pre><code><span class="code">#&lt;ACTOR answerer, running: T, state: NIL, message-box: #&lt;MESSAGE-BOX/DP mesgb-9541, processed messages: 0, max-queue-size: 0, queue: #&lt;QUEUE-UNBOUNDED #x3020029918FD&gt;&gt;&gt;</span></code></pre>

<p>Had we stored the actor to a variable, say <code>*answerer*</code> we
can create a child actor of that by doing:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">act:actor-of <span class="paren2">(<span class="code"><span class="special">*answerer*</span> <span class="string">"child-answerer"</span></span>)</span>
    <span class="keyword">:receive</span> 
    <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">self msg state</span>)</span>
        <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_141.html#IDX422" class="symbol"><i><span class="symbol">let</span></i></a> <span class="paren4">(<span class="code"><span class="paren5">(<span class="code">output <span class="paren6">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_75.html#IDX176" class="symbol">format</a> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_6.html#SEC6" class="symbol">nil</a> <span class="string">"~a"</span> <span class="string">"Hello-child ~a"</span> msg</span>)</span></span>)</span></span>)</span>
            <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_75.html#IDX176" class="symbol">format</a> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_266.html#IDX704" class="symbol">t</a> <span class="string">"~a~%"</span> output</span>)</span>
            <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_83.html#IDX221" class="symbol">cons</a> output state</span>)</span></span>)</span></span>)</span></span>)</span></span></code></pre>

<p>This will create a new actor on the context of the parent actor. The
context can be specified with just the parent actor instance <code>*answerer*</code>.</p>

<h5>Dispatchers <code>:pinned</code> vs. <code>:shared</code></h5>

<p>Dispatchers are somewhat alike thread pools. Dispatchers of the <code>:shared</code> type are a pool of workers. Workers are actors using a <code>:pinned</code> dispatcher. <code>:pinned</code> just means that an actor spawns its own mailbox thread.</p>

<p>So <code>:pinned</code> and <code>:shared</code> are types of dispatchers. <code>:pinned</code> spawns its own mailbox thread, <code>:shared</code> uses a worker pool to handle the mailbox messages.</p>

<p>By default an actor created using <code>actor-of</code> uses a <code>:shared</code> dispatcher type which uses the shared message dispatcher that is automatically setup in the system.<br/>
When creating an actor it is possible to specify the <code>dispatcher-id</code>. This parameter specifies which 'dispatcher' should handle the mailbox queue/messages.</p>

<p>Please see below for more info on dispatchers.</p>

<h4>Finding actors in the context</h4>

<p>If actors are not directly stored in a dynamic or lexical context they
can still be looked up and used. The <code>actor-context</code> protocol
contains a function <code>find-actors</code> which works like this:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">first <span class="paren2">(<span class="code">ac:find-actors 
                 <span class="special">*system*</span>
                 <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren4">(<span class="code">actor</span>)</span> <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_73.html#IDX157" class="symbol">string=</a> <span class="string">"answerer"</span> 
                                          <span class="paren5">(<span class="code">act-cell:name actor</span>)</span></span>)</span></span>)</span></span>)</span></span>)</span></span></code></pre>

<p><code>find-actors</code> takes as first parameter the actor context.
This can be either the actor system, or the context of an actor. The
second parameter is a test function. This example makes a string
comparison on the actor name. So the above function will output:</p>

<pre><code><span class="code">#&lt;ACTOR answerer, running: T, state: NIL, message-box: #&lt;MESSAGE-BOX/DP mesgb-9687, processed messages: 0, max-queue-size: 0, queue: #&lt;QUEUE-UNBOUNDED #x30200263C95D&gt;&gt;&gt;</span></code></pre>

<p>This function only does a simple flat search. The functionality of
looking up an actor in the system generally will be expanded upon.</p>

<h4>tell, ask-s and ask</h4>

<p>Let's send some messages.</p>

<h5>tell</h5>

<p><code>tell</code> is a fire-and-forget kind of send type. It
doesn't expect a result in return.</p>

<p>And because of that, and in order to demonstrate it does something,
it has to have a side-effect. So it dumps some string to the console
using <code>format</code>, because we couldn't otherwise <code>tell</code> if
the message was received and processed (see the
<code>*answerer*</code> actor definitions above).</p>

<pre><code><span class="code">CL-USER&gt; <span class="paren1">(<span class="code">act:tell <span class="special">*answerer*</span> <span class="string">"Foo"</span></span>)</span>
T
CL-USER&gt; 
Hello Foo</span></code></pre>

<p>So we see that <code>tell</code> returns immediately with <code>T</code>. But
to see the 'Hello Foo' it takes another hit on the return key,
because the REPL is not asynchronous.</p>

<h5>tell with sender</h5>

<p><code>tell</code> accepts a 'sender', which has to be an actor. So
we can do like this:</p>

<pre><code><span class="code">CL-USER&gt; <span class="paren1">(<span class="code">act:tell <span class="special">*child-answerer*</span> <span class="string">"Foo"</span> <span class="special">*answerer*</span></span>)</span>
T
CL-USER&gt; 
Hello-child Foo
Hello Hello-child Foo</span></code></pre>

<p>This sends \&quot;Foo\&quot; to <code>*child-answerer*</code>, but <code>*child-answerer*</code>
sends the response to <code>*answerer*</code>. So we see outputs of both
actors.</p>

<h5>ask-s</h5>

<p><code>ask-s</code> blocks until the message was processed by the
actor. This call returns the <code>car</code> part of the <code>cons</code> return of the
behavior function. Insofar an <code>ask-s</code> call is more
resource intensive than just a <code>tell</code>.</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">act:ask-s <span class="special">*answerer*</span> <span class="string">"Bar"</span></span>)</span></span></code></pre>

<p>Will respond with: 'Hello Bar'</p>

<h5>ask</h5>

<p><code>ask</code> combines both <code>ask-s</code> and
<code>tell</code>. From <code>ask-s</code> it 'inherits' returning
a result, even though it's a future result. Internally it is
implemented using <code>tell</code>. In order to wait for a result a
temporary actor is spawned that waits until it receives the result
from the actor where the message was sent to. With this received
result the future is fulfilled. So <code>ask</code> is async, it
returns immediately with a <code>future</code>. That
<code>future</code> can be queried until it is fulfilled. Better is
though to setup an <code>on-completed</code> handler function on it.</p>

<p>So we can do:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">future:on-completed
          <span class="paren2">(<span class="code">act:ask <span class="special">*answerer*</span> <span class="string">"Buzz"</span></span>)</span>
          <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">result</span>)</span>
            <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_75.html#IDX176" class="symbol">format</a> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_266.html#IDX704" class="symbol">t</a> <span class="string">"Received result: ~a~%"</span> result</span>)</span></span>)</span></span>)</span></span></code></pre>

<p>Well, one step at a time:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">act:ask <span class="special">*answerer*</span> <span class="string">"Buzz"</span></span>)</span></span></code></pre>

<p>Returns with:</p>

<pre><code><span class="code">#&lt;FUTURE promise: #&lt;PROMISE finished: NIL errored: NIL forward: NIL #x302002EAD6FD&gt;&gt;</span></code></pre>

<p>Then we can setup a completion handler on the future:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">future:on-completed 
          <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX107" class="symbol">*</a>
          <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">result</span>)</span>
            <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_75.html#IDX176" class="symbol">format</a> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_266.html#IDX704" class="symbol">t</a> <span class="string">"Received result: ~a~%"</span> result</span>)</span></span>)</span></span>)</span></span></code></pre>

<p>Remember '*' is the last result in the REPL which is the future
here.</p>

<p>This will print after a bit:</p>

<pre><code><span class="code">Hello Buzz
Received result: Hello Buzz</span></code></pre>

<h4>ask-s and ask with timeout</h4>

<p>A timeout (in seconds) can be specified for both <code>ask-s</code> and
<code>ask</code> and is done like so:</p>

<p>To demonstrate this we could setup an example 'sleeper' actor:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">ac:actor-of <span class="special">*system*</span> 
             <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code"></span>)</span> <span class="paren3">(<span class="code">act:make-actor 
                           <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren5">(<span class="code">self msg state</span>)</span>
                             <span class="paren5">(<span class="code">sleep 5</span>)</span></span>)</span></span>)</span></span>)</span></span>)</span></span></code></pre>

<p>If we store this to <code>*sleeper*</code> and do the following, the
<code>ask-s</code> will return a <code>handler-error</code> with an
<code>ask-timeout</code> condition.</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">act:ask-s <span class="special">*sleeper*</span> <span class="string">"Foo"</span> <span class="keyword">:time-out</span> 2</span>)</span></span></code></pre>

<pre><code><span class="code"><span class="paren1">(<span class="code"><span class="keyword">:HANDLER-ERROR</span> . #&lt;CL-GSERVER.UTILS:ASK-TIMEOUT #x30200319F97D&gt;</span>)</span></span></code></pre>

<p>This works similar with the <code>ask</code> only that the future will
be fulfilled with the <code>handler-error</code> <code>cons</code>.</p>

<p>To get a readable error message of the condition we can do:</p>

<pre><code><span class="code">CL-USER&gt; <span class="paren1">(<span class="code">format t <span class="string">"~a"</span> <span class="paren2">(<span class="code">cdr *</span>)</span></span>)</span>
A timeout set to 2 seconds occurred. Cause: 
#&lt;BORDEAUX-THREADS:TIMEOUT #x302002FAB73D&gt; </span></code></pre>

<h4>Long running operations in <code>receive</code></h4>

<p>Be careful with doing long running computations in the
<code>receive</code> function message handler, because it will block
message processing. It is advised to use a third-party thread-pool or a
library like <em>lparallel</em> to do the computations with and return early
from the <code>receive</code> message handler.</p>

<p>Considering the required <code>cons</code> return result of the
<code>receive</code> function, in case a result computation is delegated
to a thread-pool the <code>receive</code> function should return with
<code>(cons :no-reply &lt;state&gt;)</code>. The <code>:no-reply</code> will instruct the actor to
<em>not</em> send a result to a sender automatically should a sender be
available (for the cases of <code>tell</code> or <code>ask</code>). The
computation result can be 'awaited' for in an asynchronous manner and
a response to <code>*sender*</code> can be sent manually by just doing a
<code>(tell *sender* &lt;my-computation-result&gt;)</code>. The sender of the original
message is set to the dynamic variable <code>*sender*</code>.</p>

<p>Due to an asynchronous callback of a computation running is a separate
thread, the <code>*sender*</code> must be copied into a lexical environment because
at the time of when the callback is executed the <code>*sender*</code> can have a
different value.</p>

<p>This behavior must be part of the messaging protocol that is being
defined for the actors at play.</p>

<h4>Changing behavior</h4>

<p>An actor can change behavior. The behavior is just a lambda that has to
take three parameters:</p>

<ol>
<li>the actor's instance - usually called <code>self</code></li>
<li>the received message - maybe call <code>msg</code>?</li>
<li>the current state of the actor</li>
</ol>

<p>The behavior then can pattern match (or do some matching by other means)
on the received message alone, or in combination with the current state.</p>

<p>The default behavior of the actor is given on actor construction using
the default constructor <code>make-actor</code>.</p>

<p>During the lifetime of an actor the behavior can be changed using
<code>become</code>.</p>

<p>So we remember the <code>*answerer*</code> which responds with 'Hello Foo' when
we send <code>(act:ask-s *answerer* &quot;Foo&quot;)</code>. We can now change the behavior
with:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">act:become <span class="special">*answerer*</span> 
            <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">self msg state</span>)</span>
              <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_83.html#IDX221" class="symbol">cons</a> <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_75.html#IDX176" class="symbol">format</a> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_6.html#SEC6" class="symbol">nil</a> <span class="string">"my new behavior for: ~a"</span> msg</span>)</span> state</span>)</span></span>)</span></span>)</span></span></code></pre>

<p>When we now send <code>(act:ask-s *answerer* &quot;Foo&quot;)</code> we will get the
response: 'my new behavior for: Foo'.</p>

<p><strong>Reverting <code>become</code> / <code>unbecome</code></strong></p>

<p>To revert back to the default behavior as defined by the
<code>receive</code> function of the constructor you may call
<code>unbecome</code>.</p>

<h4>Creating actors without a system</h4>

<p>It is still possible to create actors without a system. This is how you
do it:</p>

<pre><code><span class="code"><span class="comment">;; make an actor
</span><span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_143.html#IDX430" class="symbol"><i><span class="symbol">defvar</span></i></a> <span class="special">*my-actor*</span> <span class="paren2">(<span class="code">act:make-actor <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren4">(<span class="code">self msg state</span>)</span>
                                     <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_83.html#IDX221" class="symbol">cons</a> <span class="string">"Foo"</span> state</span>)</span></span>)</span>
                                   <span class="keyword">:name</span> <span class="string">"Lone-actor"</span></span>)</span></span>)</span>
<span class="comment">;; setup a thread based message box
</span><span class="paren1">(<span class="code">setf <span class="paren2">(<span class="code">act-cell:msgbox <span class="special">*my-actor*</span></span>)</span> 
      <span class="paren2">(<span class="code">make-instance 'mesgb:message-box/bt</span>)</span></span>)</span></span></code></pre>

<p>You have to take care yourself about stopping the actor and freeing
resources.</p>

<h3>Agents</h3>

<p>An Agent is a specialized Actor. It is meant primarily for maintaining
state and comes with some conveniences to do that.</p>

<p>To use an Agent import <code>cl-gserver.agent</code> package.</p>

<p>There is no need to subclass an Agent. Rather create a facade to
customize an agent. See below.</p>

<p>An Agent provides three functions to use it.</p>

<ul>
<li><code>make-agent</code> creates a new agent. Optionally specify an <code>actor-context</code> or define the kind of dispatcher the agent should use.</li>
<li><code>agent-get</code> retrieves the current state of the agent. This directly
delivers the state of the agent for performance reasons. There is no
message handling involved.</li>
<li><code>agent-update</code> updates the state of the agent</li>
<li><code>agent-update-and-get</code> updates the agent state and returns the new state.</li>
</ul>

<p>All four take a lambda. The lambda for <code>make-agent</code> does not take a
parameter. It should return the initial state of the agent. <code>agent-get</code>
and <code>agent-update</code> both take a lambda that must support one parameter.
This parameter represents the current state of the agent.</p>

<p>Let's make a simple example:</p>

<p>First create an agent with an initial state of <code>0</code>.</p>

<pre><code><span class="code"><span class="paren1">(<span class="code"><i><span class="symbol">defparameter</span></i> <span class="special">*my-agent*</span> <span class="paren2">(<span class="code">make-agent <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren4">(<span class="code"></span>)</span> 0</span>)</span></span>)</span></span>)</span></span></code></pre>

<p>Now update the state several times (<code>agent-update</code> is asynchronous and
returns <code>t</code> immediately):</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">agent-update <span class="special">*my-agent*</span> <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">state</span>)</span> <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX103" class="symbol">1+</a> state</span>)</span></span>)</span></span>)</span></span></code></pre>

<p>Finally get the state:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">agent-get <span class="special">*my-agent*</span> #'<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_168.html#IDX488" class="symbol">identity</a></span>)</span></span></code></pre>

<p>This <code>agent-get</code> just uses the <code>identity</code> function to return the state
as is.</p>

<p>So this simple agent represents a counter.</p>

<p>It is important to note that the retrieves state, i.e. with <code>identity</code>
should not be modified outside the agent.</p>

<h4>Using an agent within an actor-system</h4>

<p>The <code>make-agent</code> constructor function allows to provides an optional
<code>system</code> argument that, when given, makes the constructor create the
agent within the given actor-system. This implies that the systems
shared messages dispatcher is used for the agent and no separate thread
is created for the agents message box.</p>

<p>It also implies that the agent is destroyed then the actor-system is
destroyed.</p>

<p>However, while actors can create hierarchies, agents can not. Also the
API for creating agents in systems is different to actors. This is to
make explicit that agents are treated slightly differently than actors
even though under the hood agents are actors.</p>

<h4>Wrapping an agent</h4>

<p>While you can use the agent as in the example above it is usually
advised to wrap an agent behind a more simple facade that doesn't work
with lambdas.</p>

<p>For example could a facade for the counter above look like this:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_143.html#IDX430" class="symbol"><i><span class="symbol">defvar</span></i></a> <span class="special">*counter-agent*</span> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_6.html#SEC6" class="symbol">nil</a></span>)</span>

<span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_167.html#IDX483" class="symbol"><i><span class="symbol">defun</span></i></a> init-agent <span class="paren2">(<span class="code">initial-value</span>)</span>
  <span class="paren2">(<span class="code">setf <span class="special">*counter-agent*</span> <span class="paren3">(<span class="code">make-agent <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren5">(<span class="code"></span>)</span> initial-value</span>)</span></span>)</span></span>)</span></span>)</span>

<span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_167.html#IDX483" class="symbol"><i><span class="symbol">defun</span></i></a> increment <span class="paren2">(<span class="code"></span>)</span> <span class="paren2">(<span class="code">agent-update <span class="special">*counter-agent*</span> #'<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX103" class="symbol">1+</a></span>)</span></span>)</span>
<span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_167.html#IDX483" class="symbol"><i><span class="symbol">defun</span></i></a> decrement <span class="paren2">(<span class="code"></span>)</span> <span class="paren2">(<span class="code">agent-update <span class="special">*counter-agent*</span> #'<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX104" class="symbol">1-</a></span>)</span></span>)</span>
<span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_167.html#IDX483" class="symbol"><i><span class="symbol">defun</span></i></a> counter-value <span class="paren2">(<span class="code"></span>)</span> <span class="paren2">(<span class="code">agent-get <span class="special">*counter-agent*</span> #'<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_168.html#IDX488" class="symbol">identity</a></span>)</span></span>)</span></span></code></pre>

<p>Alternatively, one can wrap an agent inside a class and provide methods
for simplified access to it.</p>

<h3>Router</h3>

<p>A <code>Router</code> is a facade over a set of actors. Routers are
either created with a set of actors using the default constructor
<code>router:make-router</code> or actors can be added later.</p>

<p>Routers implement part of the actor protocol, so it allows to use
<code>tell</code>, <code>ask-s</code> or <code>ask</code> which it
forwards to a 'routee' (one of the actors of a router) by passing all
of the given parameters. The routee is chosen by applying a
<code>strategy</code>. The built-in default strategy a routee is chosen
randomly.</p>

<p>The <code>strategy</code> can be configured when creating a router using
the constructors <code>&amp;key</code> parameter <code>:strategy</code>. The
<code>strategy</code> is just a function that takes the number of
routees and returns a routee index to be chosen for the next operation.</p>

<p>Currently available strategies: <code>:random</code> and
<code>:round-robin</code>.</p>

<p>Custom strategies can be implemented.</p>

<h3>Dispatchers</h3>

<h4>:shared</h4>

<p>A <code>:shared</code> dispatcher is a separate facility that is set up in the <code>actor-system</code>. It consists of a configurable pool of 'dispatcher workers' (which are in fact actors). Those dispatcher workers execute the message handling in behalf of the actor and with the actors message handling code. This is protected by a lock so that ever only one dispatcher will run code on an actor. This is to ensure protection from data race conditions of the state data of the actor (or other slots of the actor).</p>

<p>Using this dispatcher allows to create a large number of actors. The actors as such are generally very cheap.</p>

<p><img alt="" src="./docs/disp_shared.png" width="700"/>
<img alt="" src="disp_shared.png" width="700"/></p>

<h4>:pinned</h4>

<p>The <code>:pinned</code> dispatcher is represented by a thread that operates on the actors message queue. It handles one message after the other with the actors message handling code. This also ensures protection from data race conditions of the state of the actor.</p>

<p>This variant is slightly faster (see below) but requires one thread per actor.</p>

<p><img alt="" src="./docs/disp_pinned.png" width="700"/>
<img alt="" src="disp_pinned.png" width="700"/></p>

<h4>custom dispatcher</h4>

<p>It is also possible to create additional dispatcher of type <code>:shared</code>. A name can be freely chosen, but by convention it should be a global symbol, i.e. <code>:my-dispatcher</code>.</p>

<p>When creating actors using <code>act:actor-of</code>, or when using the <code>tasks</code> api it is possible to specify the dispatcher (via the 'dispatcher-id' i.e. <code>:my-dispatcher</code>) that should handle the actor, agent, or task messages.</p>

<p>A custom dispatcher is in particular useful when using <code>tasks</code> for longer running operations. Longer running operations should not be used for the <code>:shared</code> dispatcher because it (by default) is responsible for the message handling of most actors.</p>

<h3>Eventstream</h3>

<p>The eventstream allows messages (or events) to be posted on the eventstream in a fire-and-forget kind of way. Actors can subscribe to the eventstream if they want to get notified for particular messages or generally on all messages posted.<br/>
This allows to create event-based systems.</p>

<p>Here is a simple example:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code"><i><span class="symbol">defparameter</span></i> <span class="special">*sys*</span> <span class="paren2">(<span class="code">asys:make-actor-system</span>)</span></span>)</span>

<span class="paren1">(<span class="code">act:actor-of <span class="paren2">(<span class="code"><span class="special">*sys*</span> <span class="string">"listener"</span></span>)</span>
  <span class="keyword">:init</span> <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">self</span>)</span>
          <span class="paren3">(<span class="code">ev:subscribe self self '<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_71.html#IDX149" class="symbol">string</a></span>)</span></span>)</span>
  <span class="keyword">:receive</span> <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">self msg state</span>)</span>
             <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_126.html#IDX389" class="symbol"><i><span class="symbol">cond</span></i></a>
               <span class="paren4">(<span class="code"><span class="paren5">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_73.html#IDX157" class="symbol">string=</a> <span class="string">"my-message"</span> msg</span>)</span>
                <span class="paren5">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_75.html#IDX176" class="symbol">format</a> <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_266.html#IDX704" class="symbol">t</a> <span class="string">"received event: ~a~%"</span> msg</span>)</span></span>)</span></span>)</span>
             <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_83.html#IDX221" class="symbol">cons</a> <span class="keyword">:no-reply</span> state</span>)</span></span>)</span></span>)</span>

<span class="paren1">(<span class="code">ev:publish <span class="special">*sys*</span> <span class="string">"my-message"</span></span>)</span></span></code></pre>

<p>This subscribes to all <code>'string</code> based events and just prints the message when received.<br/>
The subscription here is done using the <code>:init</code> hook of the actor. The <code>ev:subscribe</code> function requires to specify the eventstream as first argument. But there are different variants of the generic function defined which allows to specofy an actor directly. The eventstream is retrieve from the actor through its actor-context.</p>

<pre><code><span class="code">received event: my-message</span></code></pre>

<p>See the <a href="https://mdbergmann.github.io/cl-gserver/cl-gserver.html#toc-2-7-eventstream" >API documentation</a> for more details.</p>

<h3>Tasks</h3>

<p>'tasks' is a convenience package that makes dealing with asynchronous and concurrent operations very easy.</p>

<p>Here is a simple example:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code"><i><span class="symbol">defparameter</span></i> <span class="special">*sys*</span> <span class="paren2">(<span class="code">make-actor-system</span>)</span></span>)</span>

<span class="paren1">(<span class="code"><i><span class="symbol">with-context</span></i> <span class="paren2">(<span class="code"><span class="special">*sys*</span></span>)</span>
  
  // run something without requiring a feedback
  <span class="paren2">(<span class="code">task-start <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren4">(<span class="code"></span>)</span> <span class="paren4">(<span class="code">do-lengthy-IO</span>)</span></span>)</span>
  
  // run asynchronous <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX106" class="symbol">-</a> with await
  <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_141.html#IDX422" class="symbol"><i><span class="symbol">let</span></i></a> <span class="paren4">(<span class="code"><span class="paren5">(<span class="code">task <span class="paren6">(<span class="code">task-async <span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren2">(<span class="code"></span>)</span> <span class="paren2">(<span class="code">do-a-task</span>)</span></span>)</span></span>)</span></span>)</span></span>)</span>
    // do some other stuff
    // eventually we need <i><span class="symbol">the</span></i> task result
    <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX105" class="symbol">+</a> <span class="paren5">(<span class="code">task-await task</span>)</span> 5</span>)</span></span>)</span>
    
  // run asynchronous with completion-handler <span class="paren3">(<span class="code">continuation</span>)</span>
  <span class="paren3">(<span class="code">task-async <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren5">(<span class="code"></span>)</span> <span class="paren5">(<span class="code">some-bigger-computation</span>)</span></span>)</span>
              <span class="keyword">:on-complete-fun</span>
              <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren5">(<span class="code">result</span>)</span>
                <span class="paren5">(<span class="code">do-something-with result</span>)</span></span>)</span></span>)</span>

  // concurrently map over <i><span class="symbol">the</span></i> given <a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_83.html#IDX225" class="symbol">list</a>
  <span class="paren3">(<span class="code">-&gt;&gt; 
    '<span class="paren4">(<span class="code">1 2 3 4 5</span>)</span>
    <span class="paren4">(<span class="code">task-async-stream #'<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX103" class="symbol">1+</a></span>)</span>
    <span class="paren4">(<span class="code">reduce #'<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX105" class="symbol">+</a></span>)</span></span>)</span></span>)</span>

=&gt; 20 <span class="paren2">(<span class="code">5 bits, #x14, #o24, #b10100</span>)</span>
</span></span></span></code></pre>

<p>All functions available in 'tasks' package require to be wrapped in a <code>with-context</code> macro. This macro removes the necessity of an additional argument to each of the functions which is instead supplied by the macro.</p>

<p>What happens in this example is that the list <code>'(1 2 3 4 5)</code> is passed to <code>task-async-stream</code>.
<code>task-async-stream</code> then spawns a 'task' for each element of the list and applies the given function (here <code>1+</code>) on each list element. The function though is executed by a worker of the actor-systems <code>:shared</code> dispatcher. <code>task-async-stream</code> then also collects the result of all workers. In the last step (<code>reduce</code>) the sum of the elements of the result list are calculated.</p>

<p>It is possible to specify a second argument to the <code>with-context</code> macro to specify the dispatcher that should be used for the tasks.<br/>
The concurrency here depends on the number of dispatcher workers.</p>

<p>Be also aware that the <code>:shared</code> dispatcher should not run long running operations as it blocks a message processing thread. Create a custom dispatcher to use for <code>tasks</code> when you plan to operate longer running operations.</p>

<p>See the <a href="https://mdbergmann.github.io/cl-gserver/cl-gserver.html#toc-2-8-tasks" >API documentation</a> for more details.</p>

<h3>Immutability</h3>

<p>Some words on immutability. cl-gserver does <em>not</em> make deep copies of the actor states. So whatever is returned from <code>receive</code> function as part of the <code>(cons back-msg state)</code> is just <code>setf</code>ed to the actor state. The user is responsible to make deep copies if necessary in an immutable environment. The user is responsible to <em>not</em> implictly modify the actor state outside of the actor.</p>

<h3>Benchmarks</h3>

<p><img src="./docs/perf.png" alt="" />
<img src="perf.png" alt="" /></p>

<p>Hardware specs:</p>

<ul>
<li>iMac Pro (2017) with 8 Core Xeon, 32 GB RAM</li>
</ul>

<p><strong>All</strong></p>

<p>The benchmark was created by having 8 threads throwing each 125k (1m
alltogether) messages at 1 actor. The timing was taken for when the
actor did finish processing those 1m messages. The messages were sent by
either all <code>tell</code>, <code>ask-s</code>, or <code>ask</code> to
an actor whose message-box worked using a single thread
(<code>:pinned</code>) or a dispatched message queue
(<code>:shared</code> / <code>dispatched</code>) with 8 workers.</p>

<p>Of course a <code>tell</code> is in most cases the fastest one, because
it's the least resource intensive and there is no place that is
blocking in this workflow.</p>

<p><strong>SBCL (v2.0.10)</strong></p>

<p>Even though SBCL is by far the fastest one with <code>tell</code> on
both <code>:pinned</code> and <code>dispatched</code>, it had massive
problems on <code>dispatched - ask-s</code> where I had to lower the
number of messages to 200k alltogether. Beyond that value SBCL didn't
get it worked out.</p>

<p><strong>CCL (v1.12)</strong></p>

<p>CCL is on acceptable average speed. The problems CCL had was heap
exhaustion for both the <code>ask</code> tasks where the number of
messages had to be reduced to 80k. Which is not a lot. Beyond this value
the runtime would crash. However, CCL for some reason had no problems
where SBCL was struggling with the <code>dispatched - ask-s</code>.</p>

<p><strong>ABCL (1.8)</strong></p>

<p>The pleasant surprise was ABCL. While not being the fastest it is the
most robust. Where SBCL and CCL were struggling you could throw anything
at ABCL and it'll cope with it. I'm assuming that this is because of
the massively battle proven Java Runtime.</p>

<p><a id='x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EDOCS-3A-40README-20MGL-PAX-3ASECTION-29" title="Introduction">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40CL-GSERVER-20MGL-PAX-3ASECTION-29" title="cl-gserver documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-40ACTOR-SYSTEM-20MGL-PAX-3ASECTION-29" title="Actor-System">&#8594;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8634;</a></span></span></p>

<h2><a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29">2 API documentation</a></h2>

<p><a id='x-28CL-GSERVER-2EACTOR-SYSTEM-3A-40ACTOR-SYSTEM-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40ACTOR-CONTEXT-20MGL-PAX-3ASECTION-29" title="Actor-Context">&#8594;</a> <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-40ACTOR-SYSTEM-20MGL-PAX-3ASECTION-29" title="Actor-System">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-40ACTOR-SYSTEM-20MGL-PAX-3ASECTION-29">2.1 Actor-System</a></h3>

<h6>[in package CL-GSERVER.ACTOR-SYSTEM with nicknames ASYS]</h6>

<p><a id='x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" >ACTOR-SYSTEM</a></span></span></span></p>

<p>An <code>actor-system</code> is the opening facility. The first thing you do is to create an <code>actor-system</code> using the main constructor <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AMAKE-ACTOR-SYSTEM-20FUNCTION-29" title="(CL-GSERVER.ACTOR-SYSTEM:MAKE-ACTOR-SYSTEM FUNCTION)"><code>make-actor-system</code></a>.
With the <code>actor-system</code> you can create actors via the <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a> protocol function: <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-OF GENERIC-FUNCTION)"><code>ac:actor-of</code></a>.</p>

<p>Or even simpler via <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-OF-20-28MGL-PAX-3AMACRO-29-29" title="(CL-GSERVER.ACTOR:ACTOR-OF (MGL-PAX:MACRO))"><code>act:actor-of</code></a> which is a convenience macro:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">act:actor-of <span class="paren2">(<span class="code"><span class="special">*system*</span></span>)</span>
                <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">self msg state</span>)</span>
                  <span class="comment">;; do stuff
</span>                  <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_83.html#IDX221" class="symbol">cons</a> <span class="string">"done"</span> state</span>)</span></span>)</span></span>)</span></span></code></pre></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-SYSTEM-3AMAKE-ACTOR-SYSTEM-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AMAKE-ACTOR-SYSTEM-20FUNCTION-29" >MAKE-ACTOR-SYSTEM</a></span></span> <span class="locative-args">&amp;OPTIONAL CONFIG</span></span></p>

<p>Creates an <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>actor-system</code></a>.
Allows to provide an optional configuration. See <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-2ADEFAULT-CONFIG-2A-20-28VARIABLE-29-29" title="(CL-GSERVER.ACTOR-SYSTEM:*DEFAULT-CONFIG* (VARIABLE))"><code>asys:*default-config*</code></a>.
If no config is provided the default config is used.
Is a config provided then it is merged with the default config.
Config options in the existing config override the default config.
See <a href="#x-28CL-GSERVER-2ECONFIG-3ACONFIG-FROM-20FUNCTION-29" title="(CL-GSERVER.CONFIG:CONFIG-FROM FUNCTION)"><code>config:config-from</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-SYSTEM-3A-2ADEFAULT-CONFIG-2A-20-28VARIABLE-29-29'></a></p>

<ul>
<li><span class=reference-bullet><span class=reference><span class="locative-type">[variable]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-2ADEFAULT-CONFIG-2A-20-28VARIABLE-29-29" >*DEFAULT-CONFIG*</a></span></span> <span class="locative-args">(:DISPATCHERS (:SHARED (:WORKERS 4 :STRATEGY :RANDOM)))</span></span></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29" >ACTOR-OF</a></span></span> <span class="locative-args">(SELF ACTOR-SYSTEM) CREATE-FUN</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-OF GENERIC-FUNCTION)"><code>ac:actor-of</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTORS-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTORS-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29" >FIND-ACTORS</a></span></span> <span class="locative-args">(SELF ACTOR-SYSTEM) TEST-FUN</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTORS-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:FIND-ACTORS GENERIC-FUNCTION)"><code>ac:find-actors</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTOR-BY-NAME-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTOR-BY-NAME-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29" >FIND-ACTOR-BY-NAME</a></span></span> <span class="locative-args">(SELF ACTOR-SYSTEM) NAME</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTOR-BY-NAME-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:FIND-ACTOR-BY-NAME GENERIC-FUNCTION)"><code>ac:find-actor-by-name</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AALL-ACTORS-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AALL-ACTORS-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-29-29-29" >ALL-ACTORS</a></span></span> <span class="locative-args">(SELF ACTOR-SYSTEM)</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AALL-ACTORS-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ALL-ACTORS GENERIC-FUNCTION)"><code>ac:all-actors</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3ASTOP-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASTOP-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29" >STOP</a></span></span> <span class="locative-args">(SELF ACTOR-SYSTEM) ACTOR</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASTOP-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:STOP GENERIC-FUNCTION)"><code>ac:stop</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3ASHUTDOWN-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASHUTDOWN-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-29-29-29" >SHUTDOWN</a></span></span> <span class="locative-args">(SELF ACTOR-SYSTEM)</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASHUTDOWN-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:SHUTDOWN GENERIC-FUNCTION)"><code>ac:shutdown</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40ACTOR-CONTEXT-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-40ACTOR-SYSTEM-20MGL-PAX-3ASECTION-29" title="Actor-System">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40AC-PROTOCOL-20MGL-PAX-3ASECTION-29" title="Actor-Context protocol">&#8594;</a> <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40ACTOR-CONTEXT-20MGL-PAX-3ASECTION-29" title="Actor-Context">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40ACTOR-CONTEXT-20MGL-PAX-3ASECTION-29">2.2 Actor-Context</a></h3>

<h6>[in package CL-GSERVER.ACTOR-CONTEXT with nicknames AC]</h6>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" >ACTOR-CONTEXT</a></span></span></span></p>

<p><code>actor-context</code> deals with creating and maintaining actors.
The <code>actor-system</code> and the <code>actor</code> itself are composed of an <code>actor-context</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AMAKE-ACTOR-CONTEXT-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AMAKE-ACTOR-CONTEXT-20FUNCTION-29" >MAKE-ACTOR-CONTEXT</a></span></span> <span class="locative-args">ACTOR-SYSTEM &amp;OPTIONAL ID</span></span></p>

<p>Creates an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a>. Requires a reference to <code>actor-system</code>
<code>id</code> is an optional value that can identify the <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a>.
Creating an actor-context manually is usually not needed.
An <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a> implements the <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a> protocol.
An <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)"><code>act:actor</code></a> contains an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20T-29-29-29" >ACTOR-OF</a></span></span> <span class="locative-args">(SELF ACTOR-CONTEXT) CREATE-FUN</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-OF GENERIC-FUNCTION)"><code>ac:actor-of</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTORS-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTORS-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20T-29-29-29" >FIND-ACTORS</a></span></span> <span class="locative-args">(SELF ACTOR-CONTEXT) TEST-FUN</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTORS-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:FIND-ACTORS GENERIC-FUNCTION)"><code>ac:find-actors</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTOR-BY-NAME-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTOR-BY-NAME-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20T-29-29-29" >FIND-ACTOR-BY-NAME</a></span></span> <span class="locative-args">(SELF ACTOR-CONTEXT) NAME</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTOR-BY-NAME-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:FIND-ACTOR-BY-NAME GENERIC-FUNCTION)"><code>ac:find-actor-by-name</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AALL-ACTORS-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AALL-ACTORS-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-29-29-29" >ALL-ACTORS</a></span></span> <span class="locative-args">(SELF ACTOR-CONTEXT)</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AALL-ACTORS-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ALL-ACTORS GENERIC-FUNCTION)"><code>ac:all-actors</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3ASTOP-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASTOP-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20T-29-29-29" >STOP</a></span></span> <span class="locative-args">(SELF ACTOR-CONTEXT) ACTOR</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASTOP-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:STOP GENERIC-FUNCTION)"><code>ac:stop</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3ASHUTDOWN-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASHUTDOWN-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-29-29-29" >SHUTDOWN</a></span></span> <span class="locative-args">(SELF ACTOR-CONTEXT)</span></span></p>

<p>See <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASHUTDOWN-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:SHUTDOWN GENERIC-FUNCTION)"><code>ac:shutdown</code></a></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3ANOTIFY-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ANOTIFY-20GENERIC-FUNCTION-29" >NOTIFY</a></span></span> <span class="locative-args">CONTEXT ACTOR NOTIFICATION</span></span></p>

<p>Notify the <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a> about something that happened to an actor.
Current exists:</p>

<ul>
<li><code>:stopped</code>: this will remove the actor from the context.</li>
</ul></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3ASYSTEM-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[reader]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASYSTEM-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-29-29" >SYSTEM</a></span></span> <span class="locative-args">ACTOR-CONTEXT</span> <span class="locative-args">(= <code>NIL</code>)</span></span></p>

<p>A reference to the <code>actor-system</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AID-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[reader]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AID-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-29-29" >ID</a></span></span> <span class="locative-args">ACTOR-CONTEXT</span> <span class="locative-args">(:ID = <code>NIL</code>)</span></span></p>

<p>The id of this actor-context. Usually a string.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-NAME-EXISTS-20CONDITION-29'></a></p>

<ul>
<li><span class=reference-bullet><span class=reference><span class="locative-type">[condition]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-NAME-EXISTS-20CONDITION-29" >ACTOR-NAME-EXISTS</a></span></span> <span class="locative-args">ERROR</span></span></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40AC-PROTOCOL-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40ACTOR-CONTEXT-20MGL-PAX-3ASECTION-29" title="Actor-Context">&#8592;</a> <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40ACTOR-CONTEXT-20MGL-PAX-3ASECTION-29" title="Actor-Context">&#8593;</a> <a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">&#8594;</a> <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40AC-PROTOCOL-20MGL-PAX-3ASECTION-29" title="Actor-Context protocol">&#8634;</a></span></span></p>

<h4><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40AC-PROTOCOL-20MGL-PAX-3ASECTION-29">2.2.1 Actor-Context protocol</a></h4>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29" >ACTOR-OF</a></span></span> <span class="locative-args">CONTEXT CREATE-FUN &amp;KEY DISPATCHER-ID QUEUE-SIZE</span></span></p>

<p>Creates and adds actors to the given context.</p>

<p>Both an <code>actor-system</code> and an <code>actor</code> are composed of an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a>.
When an <code>actor-system</code> is specified as context (<code>actor-system</code> implements parts of the protocol) then the new actor will be a new root actor.</p>

<p>When the new actor should be a child of another actor, then the <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a> of the (to be) parent <code>actor</code> should be specified.
Creating an actor via <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-OF GENERIC-FUNCTION)"><code>actor-of</code></a> will also add the <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a> as watcher of the actor. This watching can be used for different purposes. Right now the <code>actor</code> is removed from the context when it was stopped.</p>

<p>Specify the dispatcher type (<code>dispatcher-id</code>) as either:
<code>:shared</code> to have this actor use the shared message dispatcher of the context
<code>:pinned</code> to have this actor run it's own message box thread (faster, but more resource are bound.)</p>

<p>Specify <code>queue-size</code> with:
0: for a unbounded queue
gt 0: for a bounded queue (preferably a size &gt; 100)</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTORS-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTORS-20GENERIC-FUNCTION-29" >FIND-ACTORS</a></span></span> <span class="locative-args">CONTEXT TEST-FUN</span></span></p>

<p>Returns actors of this context where <code>test-fun</code> provides 'truth'.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTOR-BY-NAME-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AFIND-ACTOR-BY-NAME-20GENERIC-FUNCTION-29" >FIND-ACTOR-BY-NAME</a></span></span> <span class="locative-args">CONTEXT NAME</span></span></p>

<p>Returns an actor for the given name, when it exists.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3AALL-ACTORS-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AALL-ACTORS-20GENERIC-FUNCTION-29" >ALL-ACTORS</a></span></span> <span class="locative-args">CONTEXT</span></span></p>

<p>Retrieves all actors of this context as a list</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3ASTOP-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASTOP-20GENERIC-FUNCTION-29" >STOP</a></span></span> <span class="locative-args">CONTEXT ACTOR</span></span></p>

<p>Stops the given actor on the context. 
The context may either be an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a>, or an <code>actor-system</code>.
The actor is then also removed from the context.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CONTEXT-3ASHUTDOWN-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3ASHUTDOWN-20GENERIC-FUNCTION-29" >SHUTDOWN</a></span></span> <span class="locative-args">CONTEXT</span></span></p>

<p>Stops all actors in this context.
When the context is an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>actor-context</code></a> this still stop the actor context and all its actors.
For the <code>actor-system</code> it will stop the whole system with all actors.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3A-40AC-PROTOCOL-20MGL-PAX-3ASECTION-29" title="Actor-Context protocol">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2EACTOR-CELL-3A-40ACTOR-CELL-20MGL-PAX-3ASECTION-29" title="Actor-Cell">&#8594;</a> <a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29">2.3 Actor</a></h3>

<h6>[in package CL-GSERVER.ACTOR with nicknames ACT]</h6>

<p><a id='x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" >ACTOR</a></span></span> <span class="locative-args"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-20CLASS-29" title="(CL-GSERVER.ACTOR-CELL:ACTOR-CELL CLASS)">ACTOR-CELL</a></span></span></p>

<p>This is the <code>actor</code> class.</p>

<p>The <code>actor</code> does its message handling using the <code>receive</code> function.</p>

<p>The <code>receive</code> function has to return a <code>cons</code> constructed of a message to be sent back to caller (<code>car</code>), if applicable, and the new state of the actor (as <code>cdr</code>).
I.e.: <code>(cons &lt;my-response&gt; &lt;my-new-state&gt;)</code></p>

<p>There is asynchronous <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> (no response), a synchronous <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> and asynchronous <a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK GENERIC-FUNCTION)"><code>ask</code></a> which all can be used to send messages to the actor. The 'ask' variants provide a response from the actor where 'tell' is only fire-and-forget.</p>

<p>If the 'send' operation was <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> or <a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK GENERIC-FUNCTION)"><code>ask</code></a> then the <code>car</code> part of the <code>cons</code> result will be sent back to the caller.
In case of a <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> operation there will be no response and the <code>car</code> of the <code>cons</code> is ignored, if there is no sender (see <code>sender</code> argument to <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a>). If there is a sender defined (which must be an actor), then the <code>car</code> of the <code>cons</code> result is sent (using <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a>) to the sender.<br/>
It is possible to specify <code>:no-reply</code> as <code>car</code> of <code>cons</code> in this case (<a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> with sender), which has the effect that the result is <em>not</em> sent to the sender even if one exists. This is for the case that the user wants to handle the state and the notifications to a sender himself. It is useful when the message handling code for a particular message (in <code>receive</code>) should be executed in a special thread-pool, because long running operations within <code>receive</code> will block the message handling of the actor.</p>

<p>The <code>:no-reply</code> result works for <a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK GENERIC-FUNCTION)"><code>ask</code></a> and <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a>, because also <a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK GENERIC-FUNCTION)"><code>ask</code></a> is based on <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a>.
<a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> is really only useful if a synchronous result is required and should be avoided otherwise.</p>

<p>To stop an actors message processing in order to cleanup resouces you should <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> (or <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a>) the <code>:stop</code> message. It will respond with <code>:stopped</code> (in case of <code>ask(-s)</code>).</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AACTOR-OF-20-28MGL-PAX-3AMACRO-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[macro]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-OF-20-28MGL-PAX-3AMACRO-29-29" >ACTOR-OF</a></span></span> <span class="locative-args">(CONTEXT &amp;OPTIONAL (NAME <code>NIL</code>)) &amp;BODY BODY &amp;KEY RECEIVE (INIT <code>NIL</code>) (DISPATCHER <code>:SHARED</code>) (STATE <code>NIL</code>) (TYPE ''<a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)"><code>ACTOR</code></a>)</span></span></p>

<p>Simple interface for creating an actor.</p>

<p>This is the preferred way to create an actor that runs within an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a>.</p>

<p><strong>!!! Attention:</strong> this macro wraps the <a href="#x-28CL-GSERVER-2EACTOR-3AMAKE-ACTOR-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:MAKE-ACTOR GENERIC-FUNCTION)"><code>act:make-actor</code></a> and <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-OF GENERIC-FUNCTION)"><code>ac:actor-of</code></a> functionality to something more simple to use. 
Using this macro there is no need to use both <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-OF GENERIC-FUNCTION)"><code>ac:actor-of</code></a> and <a href="#x-28CL-GSERVER-2EACTOR-3AMAKE-ACTOR-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:MAKE-ACTOR GENERIC-FUNCTION)"><code>act:make-actor</code></a>.</p>

<p><code>context</code> is either an <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>, an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a>, or an <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)"><code>act:actor</code></a> (any type of actor).
The new actor is created in the given context.</p>

<ul>
<li><p><code>name</code> is optional. Specify when a static name is needed.</p></li>
<li><p><code>:receive</code> is required and must be a lambda with arguments 1. the actor, 2. the message, 3. the state
  Usually expressed as <code>(lambda (self msg state))</code>.</p></li>
<li><p><code>:init</code>: is an optional initialization function with one argument: the actor instance (self).
This represents a 'start' hook that is called after the actor was fully initialized.</p></li>
<li><p><code>:state</code> key can be used to initialize with a state.</p></li>
<li><p><code>:dispatcher</code> key can be used to define the message dispatcher manually.
  Options are <code>:shared</code> (default) and <code>:pinned</code>.</p></li>
<li><p><code>:type</code> can specify a custom actor class. See <a href="#x-28CL-GSERVER-2EACTOR-3AMAKE-ACTOR-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:MAKE-ACTOR GENERIC-FUNCTION)"><code>act:make-actor</code></a> for more info.</p></li>
</ul></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AMAKE-ACTOR-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AMAKE-ACTOR-20GENERIC-FUNCTION-29" >MAKE-ACTOR</a></span></span> <span class="locative-args">RECEIVE &amp;KEY NAME STATE TYPE INIT DESTROY</span></span></p>

<p>Constructs an <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)"><code>actor</code></a>.</p>

<p>Arguments:</p>

<ul>
<li><p><code>receive</code>: this is a function that must accept 3 parameters. That is:</p></li>
<li><p>the actor <code>instance</code> itself, </p></li>
<li><p>the <code>message</code> and </p></li>
<li><p>the <code>current-state</code> of the actor.</p></li>
<li><p><code>name</code>: give the actor a name. Must be unique within an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a>.</p></li>
<li><p><code>type</code>: Specify a custom actor class as the <code>:type</code> key. Defaults to 'actor.
Say you have a custom actor <code>custom-actor</code> and want <a href="#x-28CL-GSERVER-2EACTOR-3AMAKE-ACTOR-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:MAKE-ACTOR GENERIC-FUNCTION)"><code>make-actor</code></a> create an instance of it.
Then specify <code>:type 'custom-actor</code> on <a href="#x-28CL-GSERVER-2EACTOR-3AMAKE-ACTOR-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:MAKE-ACTOR GENERIC-FUNCTION)"><code>make-actor</code></a> function.
If you have additional initializations to make you can do so in <code>initialize-instance</code>.</p></li>
<li><p><code>state</code>: initialize an actor with a state. (default is <code>nil</code>)</p></li>
<li><p><code>init</code> and <code>destroy</code>: are functions that take one argument, the actor instance.
Those hooks are called on (after) initialization and (after) stop respectively.</p></li>
</ul></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" >TELL</a></span></span> <span class="locative-args">ACTOR MESSAGE &amp;OPTIONAL SENDER</span></span></p>

<p>Sends a message to the <code>actor</code>. <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> is asynchronous. There is no result.
If a <code>sender</code> is specified a message result of the target actor of the <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> will be sent back to the <code>sender</code></p>

<p>Generally <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> does not expect a response. But a <code>sender</code> can be specified as optionl parameter to <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a>.
If a <code>sender</code> is specified, then the message handling behavior will send the <code>car</code> of the <code>cons</code> result to the specified <code>sender</code>.</p>

<p>A <code>sender</code> can also be part of the message contract.</p>

<p><a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> can be used in two environments:</p>

<ol>
<li>outside an actor</li>
</ol>

<p>By default this sends a message as fire &amp; forget. Since this is not inside an actor, no actor can be inferred as <code>sender</code>. A <code>sender</code> can be defined as optional parameter as part of <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a>.</p>

<ol>
<li>inside an actors as part of the <code>receive</code> function</li>
</ol>

<p>As <code>sender</code> can be specified when <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a> is used inside of an actor. Currently the framework doesn't automatically infer the <code>sender</code> when no <code>sender</code> is explicitly specified.</p>

<p>=&gt; This is a future enhancement.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" >ASK-S</a></span></span> <span class="locative-args">ACTOR MESSAGE &amp;KEY TIME-OUT</span></span></p>

<p>Sends a message to the <code>actor</code>. <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> is synchronous and waits for a result.
Specify <code>timeout</code> if a message is to be expected after a certain time.
An <code>:handler-error</code> with <code>timeout</code> condition will be returned if the call timed out.</p>

<p><a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> assumes, no matter if <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> is issued from outside or inside an actor, that the response is delivered back to the caller. That's why <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> does block the execution until the result is available. The <code>receive</code> function handler must specify the result as the <code>car</code> of the cons result.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" >ASK</a></span></span> <span class="locative-args">ACTOR MESSAGE &amp;KEY TIME-OUT</span></span></p>

<p>This returns a <code>future</code>.
Specify <code>timeout</code> if a message is to be expected after a certain time.
An <code>:handler-error</code> with <code>timeout</code> condition will be returned is the call timed out.</p>

<p>An <a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK GENERIC-FUNCTION)"><code>ask</code></a> is similar to a <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> in that the caller gets back a result 
but it doesn't have to actively wait for it. Instead a <code>future</code> wraps the result.
However, the internal message handling is based on <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a>.
How this works is that the message to the target <code>actor</code> is not 'sent' using the callers thread
but instead an anonymous <code>actor</code> is started behind the scenes and this in fact makes tells
the message to the target <code>actor</code>. It does sent itself along as 'sender'.
The target <code>actor</code> tells a response back to the initial <code>sender</code>. When that happens and the anonymous <code>actor</code> received the response the <code>future</code> will be fulfilled with the <code>promise</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3ABECOME-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3ABECOME-20GENERIC-FUNCTION-29" >BECOME</a></span></span> <span class="locative-args">ACTOR NEW-BEHAVIOR</span></span></p>

<p>Changes the receive of the actor to the given <code>new-behavior</code> function.
The <code>new-behavior</code> function must accept 3 parameters: the actor instance, the message and the current state.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AUNBECOME-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AUNBECOME-20GENERIC-FUNCTION-29" >UNBECOME</a></span></span> <span class="locative-args">ACTOR</span></span></p>

<p>Reverts any behavior applied via <a href="#x-28CL-GSERVER-2EACTOR-3ABECOME-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:BECOME GENERIC-FUNCTION)"><code>become</code></a> back to the default <code>receive</code> function.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3ACONTEXT-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3ACONTEXT-20GENERIC-FUNCTION-29" >CONTEXT</a></span></span> <span class="locative-args">ACTOR</span></span></p>

<p>This is the <code>actor-context</code> every actor is composed of.
When the actor is created from scratch it has no <code>actor-context</code>.
When created through the <code>actor-context</code>s, or system's <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-OF-20-28MGL-PAX-3AMACRO-29-29" title="(CL-GSERVER.ACTOR:ACTOR-OF (MGL-PAX:MACRO))"><code>actor-of</code></a> function an <code>actor-context</code> will be set.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3APATH-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3APATH-20GENERIC-FUNCTION-29" >PATH</a></span></span> <span class="locative-args">ACTOR</span></span></p>

<p>The path of the actor, including the actor itself.
The path denotes a tree which starts at the system context.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AWATCH-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AWATCH-20GENERIC-FUNCTION-29" >WATCH</a></span></span> <span class="locative-args">ACTOR WATCHER</span></span></p>

<p>Registers <code>watcher</code> as a watcher of <code>actor</code>.
Watching lets the watcher know about lifecycle changes of the actor being watched.
I.e.: when it stopped. The message being sent in this case is: <code>(cons :stopped actor-instance)</code></p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AUNWATCH-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AUNWATCH-20GENERIC-FUNCTION-29" >UNWATCH</a></span></span> <span class="locative-args">ACTOR WATCHER</span></span></p>

<p>Unregisters <code>watcher</code> of <code>actor</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AWATCHERS-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AWATCHERS-20GENERIC-FUNCTION-29" >WATCHERS</a></span></span> <span class="locative-args">ACTOR</span></span></p>

<p>Returns a list of watchers of <code>actor</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3A-40ACTOR-CELL-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">&#8592;</a> <a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">&#8593;</a> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-BASE-20MGL-PAX-3ASECTION-29" title="Message-box base class">&#8594;</a> <a href="#x-28CL-GSERVER-2EACTOR-CELL-3A-40ACTOR-CELL-20MGL-PAX-3ASECTION-29" title="Actor-Cell">&#8634;</a></span></span></p>

<h4><a href="#x-28CL-GSERVER-2EACTOR-CELL-3A-40ACTOR-CELL-20MGL-PAX-3ASECTION-29">2.3.1 Actor-Cell</a></h4>

<h6>[in package CL-GSERVER.ACTOR-CELL with nicknames ACT-CELL]</h6>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-20CLASS-29" >ACTOR-CELL</a></span></span></span></p>

<p><code>actor-cell</code> is the base of the <code>actor</code>.
It is meant to encapsulate state, but also to execute async operations.
State can be changed by calling into the server via <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACALL-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CALL FUNCTION)"><code>call</code></a> or <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACAST-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CAST FUNCTION)"><code>cast</code></a>.
Where <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACALL-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CALL FUNCTION)"><code>call</code></a> is waiting for a result and <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACAST-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CAST FUNCTION)"><code>cast</code></a> does not.
For each <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACALL-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CALL FUNCTION)"><code>call</code></a> and <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACAST-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CAST FUNCTION)"><code>cast</code></a> handlers must be implemented by subclasses.</p>

<p>It uses a <code>message-box</code> to processes the received messages.
When the <code>actor</code>/<code>actor-cell</code> was created ad-hoc (out of the <code>actor-system</code>/<code>actor-context</code>),
it will not have a message-box and can't process messages.
When the <code>actor</code> is created through the <code>actor-system</code> or <code>actor-context</code>,
one can decide what kind of message-box/dispatcher should be used for the new <code>actor</code>.</p>

<p>See <code>actor-context</code> <code>actor-of</code> method for more information on this.</p>

<p>To stop an <code>actor</code> message handling and you can send the <code>:stop</code> message 
either via <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACALL-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CALL FUNCTION)"><code>call</code></a> (which will respond with <code>:stopped</code>) or <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACAST-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CAST FUNCTION)"><code>cast</code></a>.
This is to cleanup thread resources when the Gserver is not needed anymore.</p>

<p>Note: the <code>actor-cell</code> uses <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACALL-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CALL FUNCTION)"><code>call</code></a> and <a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACAST-20FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:CAST FUNCTION)"><code>cast</code></a> functions which translate to <code>ask-s</code> and <code>tell</code> on the <code>actor</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3ANAME-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[reader]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3ANAME-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-29-29" >NAME</a></span></span> <span class="locative-args">ACTOR-CELL</span> <span class="locative-args">(:NAME = (<code>STRING</code> (<code>GENSYM</code> &quot;actor-&quot;)))</span></span></p>

<p>The name of the actor/actor-cell. If no name is specified a default one is applied.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3ASTATE-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[reader]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3ASTATE-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-29-29" >STATE</a></span></span> <span class="locative-args">ACTOR-CELL</span> <span class="locative-args">(:STATE = <code>NIL</code>)</span></span></p>

<p>The encapsulated state.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3AMSGBOX-20-28MGL-PAX-3AACCESSOR-20CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[accessor]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3AMSGBOX-20-28MGL-PAX-3AACCESSOR-20CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-29-29" >MSGBOX</a></span></span> <span class="locative-args">ACTOR-CELL</span> <span class="locative-args">(= <code>NIL</code>)</span></span></p>

<p>The <code>message-box</code>. By default the <code>actor</code>/<a href="#x-28CL-GSERVER-2EACTOR-CELL-3AACTOR-CELL-20CLASS-29" title="(CL-GSERVER.ACTOR-CELL:ACTOR-CELL CLASS)"><code>actor-cell</code></a> has no message-box.
When the actor is created through the <code>actor-context</code> of an actor, or the <code>actor-system</code>
then it will be populated with a message-box.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3A-2ASENDER-2A-20-28VARIABLE-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[variable]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3A-2ASENDER-2A-20-28VARIABLE-29-29" >*SENDER*</a></span></span> <span class="locative-args">NIL</span></span></p>

<p>The <code>*sender*</code> is dynamically bound and available in <code>receive</code> function, when it is known.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3AHANDLE-CALL-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3AHANDLE-CALL-20GENERIC-FUNCTION-29" >HANDLE-CALL</a></span></span> <span class="locative-args">ACTOR-CELL MESSAGE CURRENT-STATE</span></span></p>

<p>Handles calls to the server. Must be implemented by subclasses.
The convention here is to return a <code>cons</code> with values to be returned to caller as <code>car</code>, and the new state as <code>cdr</code>.
<a href="#x-28CL-GSERVER-2EACTOR-CELL-3AHANDLE-CALL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CELL:HANDLE-CALL GENERIC-FUNCTION)"><code>handle-call</code></a> is executed in the default message dispatcher thread.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3AHANDLE-CAST-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3AHANDLE-CAST-20GENERIC-FUNCTION-29" >HANDLE-CAST</a></span></span> <span class="locative-args">ACTOR-CELL MESSAGE CURRENT-STATE</span></span></p>

<p>Handles casts to the server. Must be implemented by subclasses.
Same convention as for 'handle-call' except that no return is sent to the caller. This function returns immediately.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3APRE-START-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3APRE-START-20GENERIC-FUNCTION-29" >PRE-START</a></span></span> <span class="locative-args">ACTOR-CELL STATE</span></span></p>

<p>Generic function definition that called from <code>initialize-instance</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3AAFTER-STOP-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3AAFTER-STOP-20GENERIC-FUNCTION-29" >AFTER-STOP</a></span></span> <span class="locative-args">ACTOR-CELL</span></span></p>

<p>Generic function definition that is called after the actor cell has stopped.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3ASTOP-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3ASTOP-20GENERIC-FUNCTION-29" >STOP</a></span></span> <span class="locative-args">ACTOR-CELL</span></span></p>

<p>Stops the actor-cell.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3ACALL-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACALL-20FUNCTION-29" >CALL</a></span></span> <span class="locative-args">ACTOR-CELL MESSAGE &amp;KEY TIME-OUT</span></span></p>

<p>Send a message to a actor-cell instance and wait for a result.
Specify a timeout in seconds if you require a result within a certain period of time.
Be aware though that this is a resource intensive wait based on a waiting thread.
The result can be of different types.
Success result: <returned-state>
Unhandled result: <code>:unhandled</code>
Error result: `(cons :handler-error <condition>)'
In case of time-out the error condition is a bt:timeout.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3ACAST-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3ACAST-20FUNCTION-29" >CAST</a></span></span> <span class="locative-args">ACTOR-CELL MESSAGE &amp;OPTIONAL SENDER</span></span></p>

<p>Sends a message to a actor-cell asynchronously. There is no result.
If a `sender' is specified the result will be sent to the sender.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-CELL-3ARUNNING-P-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-CELL-3ARUNNING-P-20FUNCTION-29" >RUNNING-P</a></span></span> <span class="locative-args">ACTOR-CELL</span></span></p>

<p>Returns true if this server is running. <code>nil</code> otherwise.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-BASE-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EACTOR-CELL-3A-40ACTOR-CELL-20MGL-PAX-3ASECTION-29" title="Actor-Cell">&#8592;</a> <a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">&#8593;</a> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FBT-20MGL-PAX-3ASECTION-29" title="Message-box threaded">&#8594;</a> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-BASE-20MGL-PAX-3ASECTION-29" title="Message-box base class">&#8634;</a></span></span></p>

<h4><a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-BASE-20MGL-PAX-3ASECTION-29">2.3.2 Message-box base class</a></h4>

<h6>[in package CL-GSERVER.MESSAGEB with nicknames MESGB]</h6>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-20CLASS-29" >MESSAGE-BOX-BASE</a></span></span></span></p>

<p>The user does not need to create a message-box manually. It is automatically created and added to the <code>actor</code> when the actor is created through <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-OF-20-28MGL-PAX-3AMACRO-29-29" title="(CL-GSERVER.ACTOR:ACTOR-OF (MGL-PAX:MACRO))"><code>act:actor-of</code></a> or <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-OF-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-OF GENERIC-FUNCTION)"><code>ac:actor-of</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3ANAME-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[reader]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3ANAME-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-29-29" >NAME</a></span></span> <span class="locative-args">MESSAGE-BOX-BASE</span> <span class="locative-args">(:NAME = (<code>STRING</code> (<code>GENSYM</code> &quot;mesgb-&quot;)))</span></span></p>

<p>The name of the message-box.
The default name is concatenated of &quot;mesgb-&quot; and a <code>gensym</code> generated random number.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3AMAX-QUEUE-SIZE-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[reader]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3AMAX-QUEUE-SIZE-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-29-29" >MAX-QUEUE-SIZE</a></span></span> <span class="locative-args">MESSAGE-BOX-BASE</span> <span class="locative-args">(:MAX-QUEUE-SIZE = 0)</span></span></p>

<p>0 or nil will make an unbounded queue. 
A value <code>&gt; 0</code> will make a bounded queue.
Don't make it too small. A queue size of 1000 might be a good choice.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3ASUBMIT-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3ASUBMIT-20GENERIC-FUNCTION-29" >SUBMIT</a></span></span> <span class="locative-args">MESSAGE-BOX-BASE MESSAGE WITHREPLY-P TIME-OUT HANDLER-FUN</span></span></p>

<p>Submit a message to the mailbox to be queued and handled.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3ASTOP-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3ASTOP-20GENERIC-FUNCTION-29" >STOP</a></span></span> <span class="locative-args">MESSAGE-BOX-BASE</span></span></p>

<p>Stops the message processing.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3ASTOP-20-28METHOD-20NIL-20-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-29-29-29'></a></p>

<ul>
<li><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3ASTOP-20-28METHOD-20NIL-20-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-29-29-29" >STOP</a></span></span> <span class="locative-args">(SELF MESSAGE-BOX-BASE)</span></span></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3AWITH-SUBMIT-HANDLER-20-28MGL-PAX-3AMACRO-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[macro]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3AWITH-SUBMIT-HANDLER-20-28MGL-PAX-3AMACRO-29-29" >WITH-SUBMIT-HANDLER</a></span></span> <span class="locative-args">(MSGBOX MESSAGE WITHREPLY-P TIME-OUT) &amp;REST BODY</span></span></p>

<p>Macro to let the caller specify a message handler function.
Use this instead of <a href="#x-28CL-GSERVER-2EMESSAGEB-3ASUBMIT-20GENERIC-FUNCTION-29" title="(CL-GSERVER.MESSAGEB:SUBMIT GENERIC-FUNCTION)"><code>submit</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FBT-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-BASE-20MGL-PAX-3ASECTION-29" title="Message-box base class">&#8592;</a> <a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">&#8593;</a> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FDP-20MGL-PAX-3ASECTION-29" title="Message-box dispatched">&#8594;</a> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FBT-20MGL-PAX-3ASECTION-29" title="Message-box threaded">&#8634;</a></span></span></p>

<h4><a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FBT-20MGL-PAX-3ASECTION-29">2.3.3 Message-box threaded</a></h4>

<h6>[in package CL-GSERVER.MESSAGEB with nicknames MESGB]</h6>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-2FBT-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-2FBT-20CLASS-29" >MESSAGE-BOX/BT</a></span></span> <span class="locative-args"><a href="#x-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-20CLASS-29" title="(CL-GSERVER.MESSAGEB:MESSAGE-BOX-BASE CLASS)">MESSAGE-BOX-BASE</a></span></span></p>

<p>Bordeaux-Threads based message-box with a single thread operating on a message queue.
This is used when the actor is created using a <code>:pinned</code> dispatcher type.
There is a limit on the maximum number of actors/agents that can be created with
this kind of queue because each message-box (and with that each actor) requires exactly one thread.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3ASUBMIT-20-28METHOD-20NIL-20-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-2FBT-20T-20T-20T-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3ASUBMIT-20-28METHOD-20NIL-20-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-2FBT-20T-20T-20T-20T-29-29-29" >SUBMIT</a></span></span> <span class="locative-args">(SELF MESSAGE-BOX/BT) MESSAGE WITHREPLY-P TIME-OUT HANDLER-FUN</span></span></p>

<p>Alternatively use <a href="#x-28CL-GSERVER-2EMESSAGEB-3AWITH-SUBMIT-HANDLER-20-28MGL-PAX-3AMACRO-29-29" title="(CL-GSERVER.MESSAGEB:WITH-SUBMIT-HANDLER (MGL-PAX:MACRO))"><code>with-submit-handler</code></a> from your code to handle the message after it was 'popped' from the queue.
The <code>handler-fun</code> argument here will be <code>funcall</code>ed when the message was 'popped'.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FDP-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FBT-20MGL-PAX-3ASECTION-29" title="Message-box threaded">&#8592;</a> <a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">&#8593;</a> <a href="#x-28CL-GSERVER-2EFUTURE-3A-40FUTURE-20MGL-PAX-3ASECTION-29" title="Future (delayed-computation)">&#8594;</a> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FDP-20MGL-PAX-3ASECTION-29" title="Message-box dispatched">&#8634;</a></span></span></p>

<h4><a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FDP-20MGL-PAX-3ASECTION-29">2.3.4 Message-box dispatched</a></h4>

<h6>[in package CL-GSERVER.MESSAGEB with nicknames MESGB]</h6>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-2FDP-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-2FDP-20CLASS-29" >MESSAGE-BOX/DP</a></span></span> <span class="locative-args"><a href="#x-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-BASE-20CLASS-29" title="(CL-GSERVER.MESSAGEB:MESSAGE-BOX-BASE CLASS)">MESSAGE-BOX-BASE</a></span></span></p>

<p>This message box is a message-box that uses the <code>system</code>s <code>dispatcher</code>.
This has the advantage that an almost unlimited actors/agents can be created.
This message-box doesn't 'own' a thread. It uses the <code>dispatcher</code> to handle the message processing.
The <code>dispatcher</code> is kind of like a thread pool.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EMESSAGEB-3ASUBMIT-20-28METHOD-20NIL-20-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-2FDP-20T-20T-20T-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EMESSAGEB-3ASUBMIT-20-28METHOD-20NIL-20-28CL-GSERVER-2EMESSAGEB-3AMESSAGE-BOX-2FDP-20T-20T-20T-20T-29-29-29" >SUBMIT</a></span></span> <span class="locative-args">(SELF MESSAGE-BOX/DP) MESSAGE WITHREPLY-P TIME-OUT HANDLER-FUN</span></span></p>

<p>Submitting a message on a multi-threaded <code>dispatcher</code> is different as submitting on a single threaded message-box. On a single threaded message-box the order of message processing is guaranteed even when submitting from multiple threads. On the <code>dispatcher</code> this is not the case. The order cannot be guaranteed when messages are processed by different <code>dispatcher</code> threads. However, we still guarantee a 'single-threadedness' regarding the state of the actor. This is achieved here by protecting the <code>handler-fun</code> execution with a lock.</p>

<p>The <code>time-out</code> with the 'dispatcher mailbox' assumes that the message received the dispatcher queue
and the handler in a reasonable amount of time, so that the effective time-out applies on the actual
handling of the message on the dispatcher queue thread.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EFUTURE-3A-40FUTURE-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EMESSAGEB-3A-40MESSAGE-BOX-2FDP-20MGL-PAX-3ASECTION-29" title="Message-box dispatched">&#8592;</a> <a href="#x-28CL-GSERVER-2EACTOR-3A-40ACTOR-20MGL-PAX-3ASECTION-29" title="Actor">&#8593;</a> <a href="#x-28CL-GSERVER-2EAGENT-3A-40AGENT-20MGL-PAX-3ASECTION-29" title="Agent">&#8594;</a> <a href="#x-28CL-GSERVER-2EFUTURE-3A-40FUTURE-20MGL-PAX-3ASECTION-29" title="Future (delayed-computation)">&#8634;</a></span></span></p>

<h4><a href="#x-28CL-GSERVER-2EFUTURE-3A-40FUTURE-20MGL-PAX-3ASECTION-29">2.3.5 Future (delayed-computation)</a></h4>

<h6>[in package CL-GSERVER.FUTURE with nicknames FUTURE]</h6>

<p><a id='x-28CL-GSERVER-2EFUTURE-3AFUTURE-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EFUTURE-3AFUTURE-20CLASS-29" >FUTURE</a></span></span></span></p>

<p>The wrapped <a href="https://orthecreedence.github.io/blackbird/" >blackbird</a> <code>promise</code>, here called <code>future</code>.<br/>
Not all features of blackbird's <code>promise</code> are supported.<br/>
This <code>future</code> wrapper changes the terminology. A <code>future</code> is a delayed computation.
A <code>promise</code> is the fulfillment of the delayed computation.</p>

<p>The <code>future</code> is used as part of <a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK GENERIC-FUNCTION)"><code>act:ask</code></a> but is available as a general utility.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EFUTURE-3AMAKE-FUTURE-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EFUTURE-3AMAKE-FUTURE-20FUNCTION-29" >MAKE-FUTURE</a></span></span> <span class="locative-args">EXECUTE-FUN</span></span></p>

<p>Creates a future. <code>execute-fun</code> is the lambda that is executed when the future is created.
<code>execute-fun</code> takes a parameter which is the <code>resolve-fun</code> funtion. <code>resolve-fun</code> function
takes the <code>promise</code> as parameter which is the computed value. Calling <code>resolve-fun</code> with the promise
will fulfill the <a href="#x-28CL-GSERVER-2EFUTURE-3AFUTURE-20CLASS-29" title="(CL-GSERVER.FUTURE:FUTURE CLASS)"><code>future</code></a>.<br/>
Manually calling <code>resolve-fun</code> to fulfill the <a href="#x-28CL-GSERVER-2EFUTURE-3AFUTURE-20CLASS-29" title="(CL-GSERVER.FUTURE:FUTURE CLASS)"><code>future</code></a> is in contrast to just fulfill the <a href="#x-28CL-GSERVER-2EFUTURE-3AFUTURE-20CLASS-29" title="(CL-GSERVER.FUTURE:FUTURE CLASS)"><code>future</code></a> from a return value. The benefit of the <code>resolve-fun</code> is flexibility. In  a multi-threaded environment <code>execute-fun</code> could spawn a thread, in which case <code>execute-fun</code> would return immediately but no promise can be given at that time. The <code>resolve-fun</code> can be called from a thread and provide the promise.</p>

<p>Create a future with:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code">make-future <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren3">(<span class="code">resolve-fun</span>)</span> 
               <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_141.html#IDX422" class="symbol"><i><span class="symbol">let</span></i></a> <span class="paren4">(<span class="code"><span class="paren5">(<span class="code">promise <span class="paren6">(<span class="code">delayed-computation</span>)</span></span>)</span></span>)</span>
                 <span class="paren4">(<span class="code">bt:make-thread <span class="paren5">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren6">(<span class="code"></span>)</span>
                   <span class="paren6">(<span class="code">sleep 0.5</span>)</span>
                   <span class="paren6">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_232.html#IDX618" class="symbol">funcall</a> resolve-fun promise</span>)</span></span>)</span></span>)</span></span>)</span></span>)</span></span>)</span></span></code></pre></li>
</ul>

<p><a id='x-28CL-GSERVER-2EFUTURE-3ACOMPLETE-P-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EFUTURE-3ACOMPLETE-P-20FUNCTION-29" >COMPLETE-P</a></span></span> <span class="locative-args">FUTURE</span></span></p>

<p>Is <code>future</code> completed? Returns either <code>t</code> or <code>nil</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EFUTURE-3AON-COMPLETED-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EFUTURE-3AON-COMPLETED-20FUNCTION-29" >ON-COMPLETED</a></span></span> <span class="locative-args">FUTURE COMPLETED-FUN</span></span></p>

<p>Install an on-completion handler function on the given <code>future</code>.
If the <code>future</code> is already complete then the <code>completed-fun</code> function is called immediately.
<code>completed-fun</code> takes a parameter which represents the fulfilled promise (the value with which the <code>future</code> was fulfilled).</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EFUTURE-3AGET-RESULT-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EFUTURE-3AGET-RESULT-20FUNCTION-29" >GET-RESULT</a></span></span> <span class="locative-args">FUTURE</span></span></p>

<p>Get the computation result. If not yet available <code>:not-ready</code> is returned.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-3A-40AGENT-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EFUTURE-3A-40FUTURE-20MGL-PAX-3ASECTION-29" title="Future (delayed-computation)">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3A-40HASH-AGENT-20MGL-PAX-3ASECTION-29" title="Hash-table agent">&#8594;</a> <a href="#x-28CL-GSERVER-2EAGENT-3A-40AGENT-20MGL-PAX-3ASECTION-29" title="Agent">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2EAGENT-3A-40AGENT-20MGL-PAX-3ASECTION-29">2.4 Agent</a></h3>

<h6>[in package CL-GSERVER.AGENT with nicknames AGT]</h6>

<p><a id='x-28CL-GSERVER-2EAGENT-3AAGENT-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-20CLASS-29" >AGENT</a></span></span> <span class="locative-args"><a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)">ACTOR</a></span></span></p>

<p>Specialized <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)"><code>actor</code></a> class called <code>agent</code>.
It is meant primarily to encapsulate state.
To access state it provides <a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-GET-20FUNCTION-29" title="(CL-GSERVER.AGENT:AGENT-GET FUNCTION)"><code>agent-get</code></a> and <a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-UPDATE-20FUNCTION-29" title="(CL-GSERVER.AGENT:AGENT-UPDATE FUNCTION)"><code>agent-update</code></a> to update state.
Stop an agent with <a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-STOP-20FUNCTION-29" title="(CL-GSERVER.AGENT:AGENT-STOP FUNCTION)"><code>agent-stop</code></a> to free resources (threads).</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-3AMAKE-AGENT-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-3AMAKE-AGENT-20FUNCTION-29" >MAKE-AGENT</a></span></span> <span class="locative-args">STATE-FUN &amp;OPTIONAL ACTOR-CONTEXT DISPATCHER-ID</span></span></p>

<p>Makes a new <a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-20CLASS-29" title="(CL-GSERVER.AGENT:AGENT CLASS)"><code>agent</code></a> instance.</p>

<p><code>state-fun</code> is a function that takes no parameter and provides the initial state of the <a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-20CLASS-29" title="(CL-GSERVER.AGENT:AGENT CLASS)"><code>agent</code></a> as return value.</p>

<p><code>actor-context</code>: optionally specify an <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a> as <code>actor-context</code>. If specified the agent will be registered in the <code>system</code> and destroyed with it should the <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a> be destroyed. In addition the agent will use the systems shared message dispatcher and will <em>not</em> create it's own.</p>

<p><code>dispatcher-id</code>: the dispatcher is configurable. Default is <code>:shared</code>. But you may use also <code>:pinned</code> or a custom configured one. Be aware that <code>:shared</code> of a custom dispatcher only works if an <code>actor-context</code> was specified.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-3AAGENT-GET-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-GET-20FUNCTION-29" >AGENT-GET</a></span></span> <span class="locative-args">AGENT GET-FUN</span></span></p>

<p>Gets the current state of the <code>agent</code>.
<code>get-fun</code> must accept one parameter. That is the current-state of the <code>agent</code>.
To return the current state <code>get-fun</code> may be just the <code>identity</code> function.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-3AAGENT-UPDATE-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-UPDATE-20FUNCTION-29" >AGENT-UPDATE</a></span></span> <span class="locative-args">AGENT UPDATE-FUN</span></span></p>

<p>Updates the <code>agent</code> state.
<code>update-fun</code> must accept one parameter. That is the current state of the <code>agent</code>.
The return value of <code>update-fun</code> will be taken as the new state of the <code>agent</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-3AAGENT-UPDATE-AND-GET-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-UPDATE-AND-GET-20FUNCTION-29" >AGENT-UPDATE-AND-GET</a></span></span> <span class="locative-args">AGENT UPDATE-FUN</span></span></p>

<p>Updates the <code>agent</code> state.
<code>update-fun</code> must accept one parameter. That is the current state of the <code>agent</code>.
The return value of <code>update-fun</code> will be taken as the new state of the <code>agent</code>.
This function makes the update and returns the new value.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-3AAGENT-STOP-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-3AAGENT-STOP-20FUNCTION-29" >AGENT-STOP</a></span></span> <span class="locative-args">AGENT</span></span></p>

<p>Stops the message handling of the agent.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-2EHASH-3A-40HASH-AGENT-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EAGENT-3A-40AGENT-20MGL-PAX-3ASECTION-29" title="Agent">&#8592;</a> <a href="#x-28CL-GSERVER-2EAGENT-3A-40AGENT-20MGL-PAX-3ASECTION-29" title="Agent">&#8593;</a> <a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40DISPATCHER-20MGL-PAX-3ASECTION-29" title="Dispatcher">&#8594;</a> <a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3A-40HASH-AGENT-20MGL-PAX-3ASECTION-29" title="Hash-table agent">&#8634;</a></span></span></p>

<h4><a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3A-40HASH-AGENT-20MGL-PAX-3ASECTION-29">2.4.1 Hash-table agent</a></h4>

<h6>[in package CL-GSERVER.AGENT.HASH with nicknames AGTHASH]</h6>

<p><a id='x-28CL-GSERVER-2EAGENT-2EHASH-3AMAKE-HASH-AGENT-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3AMAKE-HASH-AGENT-20FUNCTION-29" >MAKE-HASH-AGENT</a></span></span> <span class="locative-args">CONTEXT &amp;KEY DISPATCHER-ID HASH-TABLE-ARGS</span></span></p>

<p>Creates an agent that wraps a CL hash-table.<br/>
<code>context</code>: something implementing <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a> protocol like <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>. Specifying <code>nil</code> here creates an agent outside of an actor system. The user has to take care of that himself.<br/>
<code>dispatcher-id</code>: a dispatcher. defaults to <code>:shared</code>.<br/>
<code>hash-table-args</code>: pass through to <code>make-hash-table</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-2EHASH-3AAGENT-GETHASH-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3AAGENT-GETHASH-20FUNCTION-29" >AGENT-GETHASH</a></span></span> <span class="locative-args">KEY HASH-AGENT</span></span></p>

<p>Retrieves value from hash-table, or <code>nil</code> if it doesn't exist.
See <code>cl:gethash</code> for more info.</p>

<p>This supports setting a hash using <code>setf</code> in the same way as with <code>cl:hash-table</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-2EHASH-3AAGENT-REMHASH-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3AAGENT-REMHASH-20FUNCTION-29" >AGENT-REMHASH</a></span></span> <span class="locative-args">KEY HASH-AGENT</span></span></p>

<p>Delete a hash-table entry. See <code>cl:remhash</code>.
Returns <code>t</code> if entry existed, <code>nil</code> otherwise.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EAGENT-2EHASH-3AAGENT-CLRHASH-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3AAGENT-CLRHASH-20FUNCTION-29" >AGENT-CLRHASH</a></span></span> <span class="locative-args">HASH-AGENT</span></span></p>

<p>Clears the hash-table. See <code>cl:clrhash</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3A-40DISPATCHER-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EAGENT-2EHASH-3A-40HASH-AGENT-20MGL-PAX-3ASECTION-29" title="Hash-table agent">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40SHARED-DISPATCHER-20MGL-PAX-3ASECTION-29" title="Shared dispatcher">&#8594;</a> <a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40DISPATCHER-20MGL-PAX-3ASECTION-29" title="Dispatcher">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40DISPATCHER-20MGL-PAX-3ASECTION-29">2.5 Dispatcher</a></h3>

<h6>[in package CL-GSERVER.DISPATCHER with nicknames DISP]</h6>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3ADISPATCHER-BASE-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3ADISPATCHER-BASE-20CLASS-29" >DISPATCHER-BASE</a></span></span></span></p>

<p>A <code>dispatcher</code> contains a pool of <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)"><code>actor</code></a> that operate as workers where work is dispatched to.
However, the workers are created in the given <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3AIDENTIFIER-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EDISPATCHER-3ADISPATCHER-BASE-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[reader]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3AIDENTIFIER-20-28MGL-PAX-3AREADER-20CL-GSERVER-2EDISPATCHER-3ADISPATCHER-BASE-29-29" >IDENTIFIER</a></span></span> <span class="locative-args">DISPATCHER-BASE</span> <span class="locative-args">(:IDENTIFIER = <code>NIL</code>)</span></span></p>

<p>Returns the identifier of the dispatcher.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3AMAKE-DISPATCHER-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3AMAKE-DISPATCHER-20FUNCTION-29" >MAKE-DISPATCHER</a></span></span> <span class="locative-args">ACTOR-CONTEXT IDENTIFIER &amp;REST CONFIG</span></span></p>

<p>Default constructor.
This creates a <a href="#x-28CL-GSERVER-2EDISPATCHER-3ASHARED-DISPATCHER-20CLASS-29" title="(CL-GSERVER.DISPATCHER:SHARED-DISPATCHER CLASS)"><code>disp:shared-dispatcher</code></a> with the given dispatcher config, see <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-2ADEFAULT-CONFIG-2A-20-28VARIABLE-29-29" title="(CL-GSERVER.ACTOR-SYSTEM:*DEFAULT-CONFIG* (VARIABLE))"><code>asys:*default-config*</code></a>.
Each worker is based on a <code>:pinned</code> actor meaning that it has its own thread.
Specify an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a> where actors needed in the dispatcher are created in.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-20GENERIC-FUNCTION-29" >DISPATCH</a></span></span> <span class="locative-args">DISPATCHER DISPATCHER-EXEC-FUN</span></span></p>

<p>Dispatches a function (<code>dispatch-exec-fun</code>) to a worker of the dispatcher to execute there.
<a href="#x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-20GENERIC-FUNCTION-29" title="(CL-GSERVER.DISPATCHER:DISPATCH GENERIC-FUNCTION)"><code>dispatch</code></a> does a <code>ask-s</code> to a <code>dispatcher</code> worker, which means this call will block.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-ASYNC-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-ASYNC-20GENERIC-FUNCTION-29" >DISPATCH-ASYNC</a></span></span> <span class="locative-args">DISPATCHER DISPATCHER-EXEC-FUN</span></span></p>

<p>Dispatches a function to a worker of the dispatcher to execute there.
<a href="#x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-ASYNC-20GENERIC-FUNCTION-29" title="(CL-GSERVER.DISPATCHER:DISPATCH-ASYNC GENERIC-FUNCTION)"><code>dispatch-async</code></a> does a <code>tell</code> to a <code>dispatcher</code> worker and is asynchronous.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3ASTOP-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3ASTOP-20GENERIC-FUNCTION-29" >STOP</a></span></span> <span class="locative-args">DISPATCHER</span></span></p>

<p>Stops the dispatcher. Stops all workers.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3AWORKERS-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3AWORKERS-20GENERIC-FUNCTION-29" >WORKERS</a></span></span> <span class="locative-args">DISPATCHER</span></span></p>

<p>Returns the workers of this dispatcher.
But better do not touch them.
Only use the defined interface here to talk to them.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-WORKER-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-WORKER-20CLASS-29" >DISPATCH-WORKER</a></span></span> <span class="locative-args"><a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)">ACTOR</a></span></span></p>

<p>Specialized <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)"><code>actor</code></a> used as <code>worker</code> is the message <code>dispatcher</code>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3AMAKE-DISPATCHER-WORKER-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3AMAKE-DISPATCHER-WORKER-20FUNCTION-29" >MAKE-DISPATCHER-WORKER</a></span></span> <span class="locative-args">NUM ACTOR-CONTEXT DISPATCHER-IDENT</span></span></p>

<p>Constructor for creating a worker.
<code>num</code> only has the purpose to give the worker a name which includes a number.
`dispatcher-ident is the dispatcher identifier.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3A-40SHARED-DISPATCHER-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40DISPATCHER-20MGL-PAX-3ASECTION-29" title="Dispatcher">&#8592;</a> <a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40DISPATCHER-20MGL-PAX-3ASECTION-29" title="Dispatcher">&#8593;</a> <a href="#x-28CL-GSERVER-2EROUTER-3A-40ROUTER-20MGL-PAX-3ASECTION-29" title="Router">&#8594;</a> <a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40SHARED-DISPATCHER-20MGL-PAX-3ASECTION-29" title="Shared dispatcher">&#8634;</a></span></span></p>

<h4><a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40SHARED-DISPATCHER-20MGL-PAX-3ASECTION-29">2.5.1 Shared dispatcher</a></h4>

<p><a id='x-28CL-GSERVER-2EDISPATCHER-3ASHARED-DISPATCHER-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EDISPATCHER-3ASHARED-DISPATCHER-20CLASS-29" >SHARED-DISPATCHER</a></span></span> <span class="locative-args"><a href="#x-28CL-GSERVER-2EDISPATCHER-3ADISPATCHER-BASE-20CLASS-29" title="(CL-GSERVER.DISPATCHER:DISPATCHER-BASE CLASS)">DISPATCHER-BASE</a></span></span></p>

<p>A shared dispatcher.
Internally it uses a <a href="#x-28CL-GSERVER-2EROUTER-3AROUTER-20CLASS-29" title="(CL-GSERVER.ROUTER:ROUTER CLASS)"><code>router:router</code></a> to drive the <a href="#x-28CL-GSERVER-2EDISPATCHER-3ADISPATCH-WORKER-20CLASS-29" title="(CL-GSERVER.DISPATCHER:DISPATCH-WORKER CLASS)"><code>dispatch-worker</code></a>s.
The default strategy of choosing a worker is <code>:random</code>.</p>

<p>A <code>shared-dispatcher</code> is automatically setup by an <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EROUTER-3A-40ROUTER-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EDISPATCHER-3A-40SHARED-DISPATCHER-20MGL-PAX-3ASECTION-29" title="Shared dispatcher">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3A-40EVENTSTREAM-20MGL-PAX-3ASECTION-29" title="Eventstream">&#8594;</a> <a href="#x-28CL-GSERVER-2EROUTER-3A-40ROUTER-20MGL-PAX-3ASECTION-29" title="Router">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2EROUTER-3A-40ROUTER-20MGL-PAX-3ASECTION-29">2.6 Router</a></h3>

<h6>[in package CL-GSERVER.ROUTER with nicknames ROUTER]</h6>

<p><a id='x-28CL-GSERVER-2EROUTER-3AROUTER-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EROUTER-3AROUTER-20CLASS-29" >ROUTER</a></span></span></span></p>

<p>A router combines a pool of actors and implements the actor-api protocol.
So a <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>tell</code></a>, <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>ask-s</code></a> and <a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK GENERIC-FUNCTION)"><code>ask</code></a> is delegated to one of the routers routees.
While a router implements parts of the actor protocol it doesn't implement all.
I.e. a router cannot be <code>watch</code>ed.
A router <code>strategy</code> defines how one of the actors is determined as the forwarding target of the message.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EROUTER-3AMAKE-ROUTER-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EROUTER-3AMAKE-ROUTER-20FUNCTION-29" >MAKE-ROUTER</a></span></span> <span class="locative-args">&amp;KEY STRATEGY ROUTEES</span></span></p>

<p>Default constructor of router.
Built-in strategies: <code>:random</code>, <code>:round-robin</code>.
Specify your own strategy by providing a function that takes a <code>fixnum</code> as parameter which represents the number of routees and returns a <code>fixnum</code> that represents the index of the routee to choose.</p>

<p>Specify <a href="#x-28CL-GSERVER-2EROUTER-3AROUTEES-20FUNCTION-29" title="(CL-GSERVER.ROUTER:ROUTEES FUNCTION)"><code>routees</code></a> if you know them upfront.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EROUTER-3AADD-ROUTEE-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EROUTER-3AADD-ROUTEE-20FUNCTION-29" >ADD-ROUTEE</a></span></span> <span class="locative-args">ROUTER ROUTEE</span></span></p>

<p>Adds a routee/actor to the router.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EROUTER-3ASTOP-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EROUTER-3ASTOP-20FUNCTION-29" >STOP</a></span></span> <span class="locative-args">ROUTER</span></span></p>

<p>Stops all routees.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EROUTER-3AROUTEES-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EROUTER-3AROUTEES-20FUNCTION-29" >ROUTEES</a></span></span> <span class="locative-args">ROUTER</span></span></p>

<p>Returns the routees as list.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3ATELL-20-28METHOD-20NIL-20-28CL-GSERVER-2EROUTER-3AROUTER-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20-28METHOD-20NIL-20-28CL-GSERVER-2EROUTER-3AROUTER-20T-29-29-29" >TELL</a></span></span> <span class="locative-args">(SELF ROUTER) MESSAGE</span></span></p>

<p>Posts the message to one routee. The routee is chosen from the router <code>strategy</code>.
Otherwise see: <a href="#x-28CL-GSERVER-2EACTOR-3ATELL-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:TELL GENERIC-FUNCTION)"><code>act:tell</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AASK-S-20-28METHOD-20NIL-20-28CL-GSERVER-2EROUTER-3AROUTER-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20-28METHOD-20NIL-20-28CL-GSERVER-2EROUTER-3AROUTER-20T-29-29-29" >ASK-S</a></span></span> <span class="locative-args">(SELF ROUTER) MESSAGE</span></span></p>

<p>Posts the message to one routee. The routee is chosen from the router <code>strategy</code>.
Otherwise see: <a href="#x-28CL-GSERVER-2EACTOR-3AASK-S-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK-S GENERIC-FUNCTION)"><code>act:ask-s</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EACTOR-3AASK-20-28METHOD-20NIL-20-28CL-GSERVER-2EROUTER-3AROUTER-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EACTOR-3AASK-20-28METHOD-20NIL-20-28CL-GSERVER-2EROUTER-3AROUTER-20T-29-29-29" >ASK</a></span></span> <span class="locative-args">(SELF ROUTER) MESSAGE</span></span></p>

<p>Posts the message to one routee. The routee is chosen from the router <code>strategy</code>.
Otherwise see: <a href="#x-28CL-GSERVER-2EACTOR-3AASK-20GENERIC-FUNCTION-29" title="(CL-GSERVER.ACTOR:ASK GENERIC-FUNCTION)"><code>act:ask</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3A-40EVENTSTREAM-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EROUTER-3A-40ROUTER-20MGL-PAX-3ASECTION-29" title="Router">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2ETASKS-3A-40TASKS-20MGL-PAX-3ASECTION-29" title="Tasks">&#8594;</a> <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3A-40EVENTSTREAM-20MGL-PAX-3ASECTION-29" title="Eventstream">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3A-40EVENTSTREAM-20MGL-PAX-3ASECTION-29">2.7 Eventstream</a></h3>

<h6>[in package CL-GSERVER.EVENTSTREAM with nicknames EV]</h6>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[class]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" >EVENTSTREAM</a></span></span></span></p>

<p>Eventstream facility allows to post/publish messages/events in the <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>
and actors that did subscribe, to listen on those events.</p>

<p>The eventstream is driven by an actor. The processing of the sent events is guaranteed to be as they arrive.</p>

<p>Events can be posted as plain strings, as lists, or as objects of classes.
The subscriber has a variaty of options to define what to listen for.</p>

<p>For example: a subscriber wants to listen to events/messages with the string &quot;Foo&quot;.
The subscriber is then only notified when events are posted with the exact same string.</p>

<p>See more information at the <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20GENERIC-FUNCTION-29" title="(CL-GSERVER.EVENTSTREAM:SUBSCRIBE GENERIC-FUNCTION)"><code>ev:subscribe</code></a> function.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3AMAKE-EVENTSTREAM-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AMAKE-EVENTSTREAM-20FUNCTION-29" >MAKE-EVENTSTREAM</a></span></span> <span class="locative-args">ACTOR-CONTEXT</span></span></p>

<p>Creating an eventstream is done by the <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a> which is then available system wide. 
But in theory it can be created individually by just passing an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a> (though I don't know what would be the reason to create an eventstream for the context of a single actor. Maybe to address only a certain hierarchy in the actor tree.)</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20GENERIC-FUNCTION-29" >SUBSCRIBE</a></span></span> <span class="locative-args">EVENTSTREAM SUBSCRIBER &amp;OPTIONAL PATTERN</span></span></p>

<p>Subscribe to the eventstream to receive notifications of certain events or event types.</p>

<p><code>subscriber</code> must be an actor (or agent).</p>

<p>The <code>pattern</code> can be:</p>

<ul>
<li><p>nil: receive all events posted to the eventstream.</p></li>
<li><p>a type, class type: this allows to get notifications when an instance of this type, or class type is posted.
I.e. if you want to listen to all string messages posted to the ev, thewn subscribe to <code>'string</code>.
Or if you want to listen to all lists, subscribe with <code>'cons</code>.</p></li>
<li><p>a symbol or global symbol: if posted message is a symbol or global symbol then the symbols are compared (<code>eq</code>).</p></li>
<li><p>a string: in which case an exact string comparison is made for a string message that is posted to the eventstream (<code>string=</code>).</p></li>
<li><p>a list: if subscription if for a list structure, and the posted message is also a list structure, then a structure comparison (<code>equalp</code>) is made.</p></li>
</ul></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3AUNSUBSCRIBE-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AUNSUBSCRIBE-20GENERIC-FUNCTION-29" >UNSUBSCRIBE</a></span></span> <span class="locative-args">EVENTSTREAM UNSUBSCRIBER</span></span></p>

<p>Unsubscribe from the eventstream. No more events will be received then.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3APUBLISH-20GENERIC-FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[generic-function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3APUBLISH-20GENERIC-FUNCTION-29" >PUBLISH</a></span></span> <span class="locative-args">EVENTSTREAM MESSAGE</span></span></p>

<p>Publish an event/message to the eventstream. Subscribers may receive notification if they registered for the right message pattern.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29" >SUBSCRIBE</a></span></span> <span class="locative-args">(EV-STREAM EVENTSTREAM) (SUBSCRIBER ACTOR)</span></span></p>

<p>Subscribe to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29" >SUBSCRIBE</a></span></span> <span class="locative-args">(SYSTEM ACTOR-SYSTEM) (SUBSCRIBER ACTOR)</span></span></p>

<p>Convenience. Allows to subscribe to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a> by just providing the <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-3AACTOR-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3ASUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-3AACTOR-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29" >SUBSCRIBE</a></span></span> <span class="locative-args">(ACTOR ACTOR) (SUBSCRIBER ACTOR)</span></span></p>

<p>Convenience. Allows to subscribe to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a> by just providing the actor.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3AUNSUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AUNSUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29" >UNSUBSCRIBE</a></span></span> <span class="locative-args">(EV-STREAM EVENTSTREAM) (UNSUBSCRIBER ACTOR)</span></span></p>

<p>Unsubscribe to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3AUNSUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AUNSUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29" >UNSUBSCRIBE</a></span></span> <span class="locative-args">(SYSTEM ACTOR-SYSTEM) (UNSUBSCRIBER ACTOR)</span></span></p>

<p>Convenience. Allows to unsubscribe to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a> by just providing the <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3AUNSUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-3AACTOR-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AUNSUBSCRIBE-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-3AACTOR-20CL-GSERVER-2EACTOR-3AACTOR-29-29-29" >UNSUBSCRIBE</a></span></span> <span class="locative-args">(ACTOR ACTOR) (UNSUBSCRIBER ACTOR)</span></span></p>

<p>Convenience. Allows to unsubscribe to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a> by just providing the actor.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3APUBLISH-20-28METHOD-20NIL-20-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3APUBLISH-20-28METHOD-20NIL-20-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20T-29-29-29" >PUBLISH</a></span></span> <span class="locative-args">(EV-STREAM EVENTSTREAM) MESSAGE</span></span></p>

<p>Publish to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3APUBLISH-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3APUBLISH-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20T-29-29-29" >PUBLISH</a></span></span> <span class="locative-args">(SYSTEM ACTOR-SYSTEM) MESSAGE</span></span></p>

<p>Convenience. Allows to publish to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a> by just providing the <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2EEVENTSTREAM-3APUBLISH-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-3AACTOR-20T-29-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[method]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2EEVENTSTREAM-3APUBLISH-20-28METHOD-20NIL-20-28CL-GSERVER-2EACTOR-3AACTOR-20T-29-29-29" >PUBLISH</a></span></span> <span class="locative-args">(ACTOR ACTOR) MESSAGE</span></span></p>

<p>Convenience. Allows to publish to <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3AEVENTSTREAM-20CLASS-29" title="(CL-GSERVER.EVENTSTREAM:EVENTSTREAM CLASS)"><code>ev:eventstream</code></a> by just providing the actor.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2ETASKS-3A-40TASKS-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2EEVENTSTREAM-3A-40EVENTSTREAM-20MGL-PAX-3ASECTION-29" title="Eventstream">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2ECONFIG-3A-40CONFIG-20MGL-PAX-3ASECTION-29" title="Config">&#8594;</a> <a href="#x-28CL-GSERVER-2ETASKS-3A-40TASKS-20MGL-PAX-3ASECTION-29" title="Tasks">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2ETASKS-3A-40TASKS-20MGL-PAX-3ASECTION-29">2.8 Tasks</a></h3>

<h6>[in package CL-GSERVER.TASKS with nicknames TASKS]</h6>

<p><a id='x-28CL-GSERVER-2ETASKS-3AWITH-CONTEXT-20-28MGL-PAX-3AMACRO-29-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[macro]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ETASKS-3AWITH-CONTEXT-20-28MGL-PAX-3AMACRO-29-29" >WITH-CONTEXT</a></span></span> <span class="locative-args">(CONTEXT &amp;OPTIONAL (DISPATCHER <code>:SHARED</code>)) &amp;BODY BODY</span></span></p>

<p><a href="#x-28CL-GSERVER-2ETASKS-3AWITH-CONTEXT-20-28MGL-PAX-3AMACRO-29-29" title="(CL-GSERVER.TASKS:WITH-CONTEXT (MGL-PAX:MACRO))"><code>with-context</code></a> creates an environment where the <code>tasks</code> package functions should be used in.
<code>context</code> can be either an <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>, an <a href="#x-28CL-GSERVER-2EACTOR-CONTEXT-3AACTOR-CONTEXT-20CLASS-29" title="(CL-GSERVER.ACTOR-CONTEXT:ACTOR-CONTEXT CLASS)"><code>ac:actor-context</code></a>, or an <a href="#x-28CL-GSERVER-2EACTOR-3AACTOR-20CLASS-29" title="(CL-GSERVER.ACTOR:ACTOR CLASS)"><code>act:actor</code></a> (or subclass).
<code>dispatcher</code> specifies the dispatcher where the tasks is executed in (like thread-pool).
The tasks created using the <code>tasks</code> functions will then be created in the given context.</p>

<p>Example:</p>

<pre><code><span class="code"><span class="comment">;; create actor-system
</span><span class="paren1">(<span class="code"><i><span class="symbol">defparameter</span></i> <span class="special">*sys*</span> <span class="paren2">(<span class="code">make-actor-system</span>)</span></span>)</span>

<span class="paren1">(<span class="code"><i><span class="symbol">with-context</span></i> <span class="paren2">(<span class="code"><span class="special">*sys*</span></span>)</span>
  <span class="paren2">(<span class="code">task-yield <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren4">(<span class="code"></span>)</span> <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX105" class="symbol">+</a> 1 1</span>)</span></span>)</span></span>)</span></span>)</span>

=&gt; 2 <span class="paren1">(<span class="code">2 bits, #x2, #o2, #b10</span>)</span>
</span></code></pre>

<p>Since the default <code>:shared</code> dispatcher should mainly be used for the message dispatching, 
but not so much for longer running tasks it is possible to create an actor system with additional
dispatchers. This additional dispatcher can be utilized for <code>tasks</code>. Be aware that the config as used below is merged with the <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3A-2ADEFAULT-CONFIG-2A-20-28VARIABLE-29-29" title="(CL-GSERVER.ACTOR-SYSTEM:*DEFAULT-CONFIG* (VARIABLE))"><code>asys:*default-config*</code></a> which means that the dispatcher <code>:foo</code> here is really an additional dispatcher.</p>

<pre><code><span class="code"><span class="comment">;; create actor-system with additional (custom) dispatcher
</span><span class="paren1">(<span class="code"><i><span class="symbol">defparameter</span></i> <span class="special">*sys*</span> <span class="paren2">(<span class="code">asys:make-actor-system '<span class="paren3">(<span class="code"><span class="keyword">:dispatchers</span> <span class="paren4">(<span class="code"><span class="keyword">:foo</span> <span class="paren5">(<span class="code"><span class="keyword">:workers</span> 16</span>)</span></span>)</span></span>)</span></span>)</span></span>)</span>

<span class="paren1">(<span class="code"><i><span class="symbol">with-context</span></i> <span class="paren2">(<span class="code"><span class="special">*sys*</span> <span class="keyword">:foo</span></span>)</span>
  <span class="paren2">(<span class="code">task-yield <span class="paren3">(<span class="code"><i><span class="symbol">lambda</span></i> <span class="paren4">(<span class="code"></span>)</span> <span class="paren4">(<span class="code">+ 1 1</span>)</span></span>)</span></span>)</span></span>)</span>
</span></code></pre></li>
</ul>

<p><a id='x-28CL-GSERVER-2ETASKS-3ATASK-YIELD-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-YIELD-20FUNCTION-29" >TASK-YIELD</a></span></span> <span class="locative-args">FUN &amp;OPTIONAL TIME-OUT</span></span></p>

<p><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-YIELD-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-YIELD FUNCTION)"><code>task-yield</code></a> runs the given function <code>fun</code> by blocking and waiting for a response from the <code>task</code>, or until the given timeout was elapsed.
<code>fun</code> must be a 0-arity function.</p>

<p>A normal response from the actor is passed back as the response value.
If the timeout elapsed the response is: <code>(values :handler-error utils:ask-timeout)</code>.</p>

<p>Example:</p>

<pre><code><span class="code"><span class="comment">;; create actor-system
</span><span class="paren1">(<span class="code"><i><span class="symbol">defparameter</span></i> <span class="special">*sys*</span> <span class="paren2">(<span class="code">make-actor-system</span>)</span></span>)</span>

<span class="paren1">(<span class="code"><i><span class="symbol">with-context</span></i> <span class="paren2">(<span class="code"><span class="special">*sys*</span></span>)</span>
  <span class="paren2">(<span class="code">task-yield <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren4">(<span class="code"></span>)</span> <span class="paren4">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX105" class="symbol">+</a> 1 1</span>)</span></span>)</span></span>)</span></span>)</span>

=&gt; 2 <span class="paren1">(<span class="code">2 bits, #x2, #o2, #b10</span>)</span></span></code></pre></li>
</ul>

<p><a id='x-28CL-GSERVER-2ETASKS-3ATASK-START-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-START-20FUNCTION-29" >TASK-START</a></span></span> <span class="locative-args">FUN</span></span></p>

<p><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-START-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-START FUNCTION)"><code>task-start</code></a> runs the given function <code>fun</code> asynchronously.
<code>fun</code> must be a 0-arity function.
Use this if you don't care about any response or result, i.e. for I/O side-effects.
It returns <code>(values :ok &lt;task&gt;)</code>. `<task> is in fact an actor given back as reference.
The task is automatically stopped and removed from the context and will not be able to handle requests.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29" >TASK-ASYNC</a></span></span> <span class="locative-args">FUN &amp;KEY ON-COMPLETE-FUN</span></span></p>

<p><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-ASYNC FUNCTION)"><code>task-async</code></a> schedules the function <code>fun</code> for asynchronous execution.
<code>fun</code> must be a 0-arity function.
<code>on-complete-fun</code> is a 1-arity completion handler function. When called the result is delivered.
The completion handler function parameter may also be a <code>(cons :handler-error condition)</code> construct in case an error happened within the message handling.</p>

<p>Using <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-ASYNC FUNCTION)"><code>task-async</code></a> provides two alternatives:</p>

<ul>
<li><p>together with <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-AWAIT FUNCTION)"><code>task-await</code></a></p></li>
<li><p>or with completion handler</p></li>
</ul>

<p>In fact it is possible to call <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-AWAIT FUNCTION)"><code>task-await</code></a> as well, but then you probably don't need a completion handler.
Using the completion handler makes the processing complete asynchronous.</p>

<p>The result of <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-ASYNC FUNCTION)"><code>task-async</code></a> is a <code>task</code>.
Store this <code>task</code> for a call to <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-ASYNC FUNCTION)"><code>task-async</code></a> (even with or without using <code>on-complete-fun</code>).
When <em>not</em> using <code>on-complete-fun</code> users must call either <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-AWAIT FUNCTION)"><code>task-await</code></a> or <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-SHUTDOWN-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-SHUTDOWN FUNCTION)"><code>task-shutdown</code></a> for the task to be cleaned up.
When using <code>on-complete-fun</code> this is done for you.</p>

<p>Example:</p>

<pre><code><span class="code"><span class="comment">;; create actor-system
</span><span class="paren1">(<span class="code"><i><span class="symbol">defparameter</span></i> <span class="special">*sys*</span> <span class="paren2">(<span class="code">make-actor-system</span>)</span></span>)</span>

<span class="paren1">(<span class="code"><i><span class="symbol">with-context</span></i> <span class="paren2">(<span class="code"><span class="special">*sys*</span></span>)</span>
  <span class="paren2">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_141.html#IDX422" class="symbol"><i><span class="symbol">let</span></i></a> <span class="paren3">(<span class="code"><span class="paren4">(<span class="code">x <span class="paren5">(<span class="code">task-async <span class="paren6">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren1">(<span class="code"></span>)</span> <span class="paren1">(<span class="code">some bigger computation</span>)</span></span>)</span></span>)</span></span>)</span>
        <span class="paren4">(<span class="code">y 1</span>)</span></span>)</span>
    <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX105" class="symbol">+</a> <span class="paren4">(<span class="code">task-await x</span>)</span> y</span>)</span></span>)</span></span>)</span>

<span class="comment">;; use-case with `on-complete-fun`
</span><span class="paren1">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_167.html#IDX483" class="symbol"><i><span class="symbol">defun</span></i></a> my-task-completion <span class="paren2">(<span class="code">result</span>)</span>
  <span class="paren2">(<span class="code">do-something-with result</span>)</span></span>)</span>

<span class="paren1">(<span class="code"><i><span class="symbol">with-context</span></i> <span class="paren2">(<span class="code"><span class="special">*sys*</span></span>)</span>
  <span class="paren2">(<span class="code">task-async <span class="paren3">(<span class="code"><a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_330.html#IDX1006" class="symbol"><i><span class="symbol">lambda</span></i></a> <span class="paren4">(<span class="code"></span>)</span> <span class="paren4">(<span class="code">some-bigger-computation</span>)</span></span>)</span>
              <span class="keyword">:on-complete-fun</span> #'my-task-completion</span>)</span></span>)</span></span></code></pre></li>
</ul>

<p><a id='x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29" >TASK-AWAIT</a></span></span> <span class="locative-args">TASK &amp;OPTIONAL TIME-OUT</span></span></p>

<p><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-AWAIT FUNCTION)"><code>task-await</code></a> waits (by blocking) until a result has been generated for a previous <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-ASYNC FUNCTION)"><code>task-async</code></a> by passing the <code>task</code> result of <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-ASYNC FUNCTION)"><code>task-async</code></a> to <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-AWAIT FUNCTION)"><code>task-await</code></a>.
Specify <code>time-out</code> in seconds. If <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-AWAIT FUNCTION)"><code>task-await</code></a> times out a <code>(cons :handler-error 'ask-timeout)</code> will be returned.
<a href="#x-28CL-GSERVER-2ETASKS-3ATASK-AWAIT-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-AWAIT FUNCTION)"><code>task-await</code></a> also stops the <code>task</code> that is the result of <a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-ASYNC FUNCTION)"><code>task-async</code></a>, so it is of no further use.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2ETASKS-3ATASK-SHUTDOWN-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-SHUTDOWN-20FUNCTION-29" >TASK-SHUTDOWN</a></span></span> <span class="locative-args">TASK</span></span></p>

<p><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-SHUTDOWN-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-SHUTDOWN FUNCTION)"><code>task-shutdown</code></a> shuts down a task in order to clean up resources.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-STREAM-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-STREAM-20FUNCTION-29" >TASK-ASYNC-STREAM</a></span></span> <span class="locative-args">FUN LST</span></span></p>

<p><a href="#x-28CL-GSERVER-2ETASKS-3ATASK-ASYNC-STREAM-20FUNCTION-29" title="(CL-GSERVER.TASKS:TASK-ASYNC-STREAM FUNCTION)"><code>task-async-stream</code></a> concurrently applies <code>fun</code> on all elements of <code>lst</code>.
<code>fun</code> must be a one-arity function taking an element of <code>lst</code>.</p>

<p>The concurrency depends on the number of available <code>:shared</code> dispatcher workers.
Each element of <code>lst</code> is processed by a worker of the <a href="#x-28CL-GSERVER-2EACTOR-SYSTEM-3AACTOR-SYSTEM-20CLASS-29" title="(CL-GSERVER.ACTOR-SYSTEM:ACTOR-SYSTEM CLASS)"><code>asys:actor-system</code></a>s <code>:shared</code> dispatcher.
If all workers are busy then the computation of <code>fun</code> is queued.</p>

<p>Example:</p>

<pre><code><span class="code"><span class="comment">;; create actor-system
</span><span class="paren1">(<span class="code"><i><span class="symbol">defparameter</span></i> <span class="special">*sys*</span> <span class="paren2">(<span class="code">make-actor-system</span>)</span></span>)</span>

<span class="paren1">(<span class="code"><i><span class="symbol">with-context</span></i> <span class="paren2">(<span class="code"><span class="special">*sys*</span></span>)</span>
  <span class="paren2">(<span class="code">-&gt;&gt; 
    '<span class="paren3">(<span class="code">1 2 3 4 5</span>)</span>
    <span class="paren3">(<span class="code">task-async-stream #'<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX103" class="symbol">1+</a></span>)</span>
    <span class="paren3">(<span class="code">reduce #'<a href="http://www.gnu.org/software/emacs/elisp-manual/html_node/elisp_63.html#IDX105" class="symbol">+</a></span>)</span></span>)</span></span>)</span>

=&gt; 20 <span class="paren1">(<span class="code">5 bits, #x14, #o24, #b10100</span>)</span></span></code></pre></li>
</ul>

<p><a id='x-28CL-GSERVER-2ECONFIG-3A-40CONFIG-20MGL-PAX-3ASECTION-29'></a></p>

<p><span class="outer-navigation"><span class="navigation"> <a href="#x-28CL-GSERVER-2ETASKS-3A-40TASKS-20MGL-PAX-3ASECTION-29" title="Tasks">&#8592;</a> <a href="#x-28CL-GSERVER-2EDOCS-3A-40API-20MGL-PAX-3ASECTION-29" title="API documentation">&#8593;</a> <a href="#x-28CL-GSERVER-2ECONFIG-3A-40CONFIG-20MGL-PAX-3ASECTION-29" title="Config">&#8634;</a></span></span></p>

<h3><a href="#x-28CL-GSERVER-2ECONFIG-3A-40CONFIG-20MGL-PAX-3ASECTION-29">2.9 Config</a></h3>

<h6>[in package CL-GSERVER.CONFIG with nicknames CONFIG]</h6>

<p><a id='x-28CL-GSERVER-2ECONFIG-3ACONFIG-FROM-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ECONFIG-3ACONFIG-FROM-20FUNCTION-29" >CONFIG-FROM</a></span></span> <span class="locative-args">CONFIG-STRING</span></span></p>

<p>Parses the given config-string, represented by common lisp s-expressions.
The config is composed of plists in a hierarchy.</p>

<p>This function parses (run through <code>cl:read</code>) the given config string.
The config string can be generated by:</p>

<pre><code><span class="code"><span class="paren1">(<span class="code"><i><span class="symbol">let</span></i> <span class="paren2">(<span class="code"><span class="paren3">(<span class="code"><span class="special">*print-case*</span> <span class="keyword">:downcase</span></span>)</span></span>)</span>
  <span class="paren2">(<span class="code">prin1-to-string '<span class="paren3">(<span class="code"><i><span class="symbol">defconfig</span></i> 
                     <span class="paren4">(<span class="code"><span class="keyword">:foo</span> 1
                      <span class="keyword">:bar</span> 2</span>)</span></span>)</span></span>)</span></span>)</span></span></code></pre>

<p>Or just be given by reading from a file.
Notice the 'config' s-expr must start with the root <code>car</code> 'defconfig'.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2ECONFIG-3ARETRIEVE-SECTION-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ECONFIG-3ARETRIEVE-SECTION-20FUNCTION-29" >RETRIEVE-SECTION</a></span></span> <span class="locative-args">CONFIG SECTION</span></span></p>

<p>Retrieves the given named section which should be a (global) <code>symbol</code> (a key).
A section usually is a plist with additional configs or sub sections.
This function looks only in the root hierarchy of the given config.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2ECONFIG-3ARETRIEVE-VALUE-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ECONFIG-3ARETRIEVE-VALUE-20FUNCTION-29" >RETRIEVE-VALUE</a></span></span> <span class="locative-args">SECTION KEY</span></span></p>

<p>Retrieves the value for the given key and section.</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2ECONFIG-3ARETRIEVE-KEYS-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ECONFIG-3ARETRIEVE-KEYS-20FUNCTION-29" >RETRIEVE-KEYS</a></span></span> <span class="locative-args">CONFIG</span></span></p>

<p>Retrieves all section keys</p></li>
</ul>

<p><a id='x-28CL-GSERVER-2ECONFIG-3AMERGE-CONFIG-20FUNCTION-29'></a></p>

<ul>
<li><p><span class=reference-bullet><span class=reference><span class="locative-type">[function]</span> <span class="reference-object"><a href="#x-28CL-GSERVER-2ECONFIG-3AMERGE-CONFIG-20FUNCTION-29" >MERGE-CONFIG</a></span></span> <span class="locative-args">CONFIG FALLBACK-CONFIG</span></span></p>

<p>Merges config. 
<code>config</code> specifies a config that overrides what exists in <code>fallback-config</code>.
<code>fallback-config</code> is a default. If something doesn't exist in <code>config</code> it is taken from <code>fallback-config</code>.
Both <code>config</code> and <code>fallback-config</code> must be plists, or a 'config' that was the output of <a href="#x-28CL-GSERVER-2ECONFIG-3ACONFIG-FROM-20FUNCTION-29" title="(CL-GSERVER.CONFIG:CONFIG-FROM FUNCTION)"><code>config-from</code></a>.</p></li>
</ul>
  </div>
</div>
<script>$('#page-toc').toc({'selectors': 'h1,h2,h3,h4'});</script>
</body>
</html>
